> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 图片编辑

> 图片编辑、mask、图生图和多参考图的能力边界

图片编辑覆盖换背景、局部重绘、商品图优化、风格调整和生成变体。Tapapi 本地路由包含 `POST /v1/images/edits`，但编辑能力不是所有图片模型都支持，生产接入前必须确认模型、渠道、字段和价格。

<Warning>`/v1/tapapi/images/advanced` 不是当前稳定图生图入口。不要通过 advanced 传 `image_urls` 或 `mask` 做生产图片编辑。</Warning>

## 能力区别

| 能力   | 输入 -> 输出                       | 当前建议                             |
| ---- | ------------------------------ | -------------------------------- |
| 文生图  | text -> image                  | 稳定主线，使用 `/v1/images/generations` |
| 图生图  | text + image -> image          | 规划能力，不要用 `image_urls` 硬接         |
| 多参考图 | text + 多图 -> image             | 规划能力，等待模型白名单和计费说明                |
| 图片编辑 | image + prompt -> image        | 条件可用，仅模型明确支持时使用                  |
| 局部重绘 | image + mask + prompt -> image | 条件可用，仅模型明确支持 `mask` 时使用          |

## 图片编辑入口

```text theme={null}
POST https://tapapi.ai/v1/images/edits
```

这个接口使用 `multipart/form-data`。常见字段如下：

| 字段                | 类型      | 说明                        |
| ----------------- | ------- | ------------------------- |
| `model`           | string  | 模型名，必须是明确支持图片编辑的模型        |
| `image`           | file    | 输入图片；部分模型可用 `image[]` 传多张 |
| `prompt`          | string  | 编辑指令                      |
| `mask`            | file    | 可选，仅在模型支持局部重绘时使用          |
| `n`               | integer | 生成张数，建议先用 `1`             |
| `size`            | string  | 输出尺寸，取决于具体模型              |
| `response_format` | string  | `url` 或 `b64_json`        |

<Note>schema 里出现 `mask` 或 `image[]` 不代表所有模型都支持。以控制台可见模型、模型详情页和小样本测试为准。</Note>

## cURL 示例

```bash theme={null}
curl https://tapapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=gpt-image-1" \
  -F "image=@product.png" \
  -F "prompt=replace the background with a clean white ecommerce studio" \
  -F "response_format=url"
```

如果模型支持局部重绘，可以额外传 `mask`：

```bash theme={null}
curl https://tapapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=gpt-image-1" \
  -F "image=@product.png" \
  -F "mask=@mask.png" \
  -F "prompt=change only the background to a warm kitchen scene" \
  -F "response_format=url"
```

## 生产接入建议

* 先确认模型明确支持图片编辑，再开放给用户
* 默认 `n: 1`，每张结果单独记录状态和成本
* 保存原图、prompt、模型名、返回图片、错误码、`X-Oneapi-Request-Id` 和业务 `task_id`
* 结果返回后尽快转存到自己的对象存储
* 对 400 / 422 不重试，优先修正字段、图片格式或 prompt
* 对临时 5xx / network timeout 只做有限重试
* 不要把 `image_urls`、`mask`、`image[]` 写成所有模型通用字段

## 验收方式

| 验收项  | 标准                                         |
| ---- | ------------------------------------------ |
| 支持范围 | 目标模型明确支持 `/v1/images/edits` 或对应编辑协议        |
| 输入文件 | 图片格式、大小、数量和 mask 规则已通过小样本验证                |
| 返回处理 | 同时兼容 `url` 和 `b64_json`，并检查 `data.length`  |
| 计费排查 | 每次请求保存业务 `task_id` 和 `X-Oneapi-Request-Id` |
| 失败处理 | 400/422 不重试，临时错误有限重试并保留原始错误                |

如果只是从文字生成图片，请使用 [文生图](/image-generation/text-to-image)。图生图规划说明见 [图生图](/image-generation/image-to-image)，多参考图说明见 [多参考图](/image-generation/multi-reference)。