图片编辑调用文档

# 图片编辑调用文档

图片编辑接口根据输入图片和文本指令生成编辑后的图片，支持单图、多图及带遮罩的编辑。本文适用于 `gpt-image-2`、`gpt-image-2.5-flare` 和 `gpt-image-2.5-sunburst`，同步返回 Base64 图片及用量统计。

仅通过文字生成图片时，请使用 [图片生成接口](图片生成调用文档.md)。

## 接口信息

| 项目 | 内容 |
| --- | --- |
| 基础地址 | `https://aiproxy-api.cloudcare.cn` |
| 请求方法 | `POST` |
| 接口路径 | `/v1/images/edits` |
| 鉴权 | `Authorization: Bearer <平台 API Key>` |
| 请求类型 | `multipart/form-data` |
| 响应类型 | `application/json` |
| 调用模式 | 同步返回图片结果 |

调用示例使用环境变量 `AIPROXY_API_KEY` 传递平台 API Key。请将 `YOUR_API_KEY` 替换为实际密钥。

```bash
export AIPROXY_API_KEY='YOUR_API_KEY'
```

## 模型与调用方式

| 模型系列 | 提示词位置 | 图片输入方式 | 结果获取方式 |
| --- | --- | --- | --- |
| GPT Image 2 / 2.5 | 表单字段 `prompt` | `image`、重复的 `image[]`，以及可选的 `mask` 文件 | 响应 `data[].b64_json`，解码保存 |

## GPT Image

文件通过表单上传。使用 curl 的 `--form` 时，由 curl 自动生成包含 boundary 的 `Content-Type` 请求头，无需手动设置。

### 可用模型

| 模型名称 | 说明 |
| --- | --- |
| `gpt-image-2` | GPT Image 2 模型，支持图片生成和编辑 |
| `gpt-image-2.5-flare` | GPT Image 2.5 Flare 模型，支持图片生成和编辑 |
| `gpt-image-2.5-sunburst` | GPT Image 2.5 Sunburst 模型，支持图片生成和编辑 |

请使用当前 API Key 已开通的模型。切换模型时替换请求中的 `model` 字段，模型名称应完整填写。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型名称，取值见本节可用模型 |
| `prompt` | string | 是 | 描述需要执行的编辑 |
| `image` | file | 与 `image[]` 二选一 | 单图上传字段，例如 `@/path/to/cat.png` |
| `image[]` | file，可重复 | 与 `image` 二选一 | 多图上传字段，每张图片使用一个同名表单项 |
| `mask` | file | 否 | 用于指定编辑区域的遮罩文件，例如 `@/path/to/mask.png` |
| `n` | integer | 否 | 生成图片数量，表单中使用文本形式，例如 `1` |
| `size` | string | 否 | 图片分辨率，采用 `宽x高` 格式，例如 `1024x1024` |
| `quality` | string | 否 | 图片质量，例如 `low` |

非文件参数以文本表单字段提交，图片与 mask 以文件表单字段提交。

至少提供一张输入图片。示例统一使用 PNG 文件、`n=1`、`size=1024x1024` 和 `quality=low`。如需使用其他参数取值或文件格式，或确认图片大小、数量及 mask 的要求，请联系技术支持。

### 请求示例

#### 单图编辑

通过 `image` 上传一张图片，在 `prompt` 中描述修改目标及希望保留的内容。

```bash
curl --request POST 'https://aiproxy-api.cloudcare.cn/v1/images/edits' \
  --header "Authorization: Bearer ${AIPROXY_API_KEY}" \
  --form 'model=gpt-image-2' \
  --form 'prompt=在猫的头上添加一顶红色生日帽，其他区域尽量保持不变' \
  --form 'n=1' \
  --form 'size=1024x1024' \
  --form 'quality=low' \
  --form 'image=@/path/to/cat.png' \
  --output edit.json
```

将 `/path/to/cat.png` 替换为本地图片路径。`@` 表示读取本地文件上传，不能省略。

#### 多图编辑

多张图片使用重复的 `image[]` 字段上传，并在 `prompt` 中说明各张图片的用途。

```bash
curl --request POST 'https://aiproxy-api.cloudcare.cn/v1/images/edits' \
  --header "Authorization: Bearer ${AIPROXY_API_KEY}" \
  --form 'model=gpt-image-2.5-flare' \
  --form 'prompt=将第一张图片中的猫放到第二张图片的场景中，保持猫的外观特征' \
  --form 'n=1' \
  --form 'size=1024x1024' \
  --form 'quality=low' \
  --form 'image[]=@/path/to/image1.png' \
  --form 'image[]=@/path/to/image2.png' \
  --output edit.json
```

每张图片对应一个独立的 `--form` 参数；文件列表不应作为 JSON 数组或逗号分隔的字符串发送。

#### 带 mask 的编辑

同时上传原图 `image` 和遮罩 `mask`，使用文本描述区域内的编辑要求。

```bash
curl --request POST 'https://aiproxy-api.cloudcare.cn/v1/images/edits' \
  --header "Authorization: Bearer ${AIPROXY_API_KEY}" \
  --form 'model=gpt-image-2.5-flare' \
  --form 'prompt=在猫的头上添加一顶红色生日帽，其他区域尽量保持不变' \
  --form 'n=1' \
  --form 'size=1024x1024' \
  --form 'quality=low' \
  --form 'image=@/path/to/cat.png' \
  --form 'mask=@/path/to/mask.png' \
  --output edit.json
```

切换模型时，替换 `model` 为可用模型中的完整名称；其余表单结构相同。

### 响应示例

以下为响应结构示例，Base64 内容已缩略，用量数值仅供参考。实际图片输入 Token 数取决于本次输入。

```json
{
  "created": 1778487970,
  "background": "opaque",
  "data": [
    {
      "b64_json": "iVBORw0KG...tAAAAAElFTkSuQmCC"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 9,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 9
    },
    "output_tokens": 196,
    "total_tokens": 205
  }
}
```

#### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `created` | integer | 响应创建时间，Unix 时间戳，单位为秒 |
| `background` | string | 背景类型，示例为 `opaque` |
| `data` | array | 编辑结果图片列表 |
| `data[].b64_json` | string | 结果图片文件的 Base64 编码 |
| `output_format` | string | 输出图片格式，示例为 `png` |
| `quality` | string | 本次输出的质量 |
| `size` | string | 本次输出的图片尺寸 |
| `usage.input_tokens` | integer | 输入 Token 总量 |
| `usage.input_tokens_details.text_tokens` | integer | 输入文本 Token 数 |
| `usage.input_tokens_details.image_tokens` | integer | 输入图片 Token 数 |
| `usage.output_tokens` | integer | 输出 Token 数 |
| `usage.total_tokens` | integer | 总 Token 数 |

编辑在当前 HTTP 请求中完成，直接返回结果图片，无需轮询或设置异步请求头。

### 保存图片

执行成功后，使用 Python 将 `edit.json` 中的图片解码保存：

```bash
python3 - <<'PY'
import base64
import json
from pathlib import Path

result = json.loads(Path('edit.json').read_text())
for index, item in enumerate(result['data'], start=1):
    path = Path(f'edited_{index}.png')
    path.write_bytes(base64.b64decode(item['b64_json'], validate=True))
    print(path)
PY
```

此示例对应 `output_format=png`；其他格式应使用相应的文件扩展名。请使用真实接口返回的完整 Base64 数据解码。

## 错误处理

请求失败时，请检查 HTTP 状态码和响应中的 `error` 对象。以下为参数错误的响应结构示例：

```json
{
  "error": {
    "message": "model is required",
    "type": "ee_proxy_error",
    "code": "invalid_request"
  },
  "request_id": "request-example"
}
```

`error.message` 为错误说明，`error.code` 为错误标识；`request_id` 有值时返回。常见 HTTP 状态码及处理方式如下：

| HTTP 状态码 | 说明 | 处理方式 |
| --- | --- | --- |
| `400` | 请求参数不合法 | 检查必填字段、请求格式及参数取值 |
| `401` | 鉴权失败 | 检查是否携带有效的 API Key |
| `403` | 无权访问或额度受限 | 检查模型访问权限及可用额度 |
| `429` | 请求频率受限 | 降低请求频率，等待后重试 |
| `503` | 服务暂时无法完成请求 | 稍后重试；持续失败时联系技术支持 |

排查问题时，请提供调用时间、模型名称、HTTP 状态码、错误响应，以及响应头 `X-EE-Response-ID`。

请求超时后重新提交可能再次生成图片并产生费用。