GPT-Image-2.5-Flare 图像编辑 - 数字先锋API文档

# GPT-Image-2.5-Flare 图生图（图像编辑）API 对接文档

> **用途**：第三方软件 / 自有应用对接「GPT-Image-2.5-Flare 图生图 / 图像编辑」能力
> **平台**：云灵API（api.cxsee.com）
> **接口**：`POST /v1/images/edits`（OpenAI 兼容，**multipart/form-data**）

---

## 1. 快速开始

上传一张图片 + 一段修改描述，返回编辑后的新图：

```bash
curl -X POST "https://api.cxsee.com/v1/images/edits" \
  -H "Authorization: Bearer <你的API令牌>" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=把房子的屋顶改成蓝色，并在天空加几朵白云" \
  -F "image=@input.png" \
  -F "size=1024x1024" \
  -F "response_format=url"
```

```json
{
  "background": "opaque",
  "created": 1789153068,
  "data": [
    { "url": "https://.../0.png?X-Amz-Algorithm=..." }
  ],
  "model": "gpt-image-2.5-flare",
  "moderation": "",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 1047,
    "input_tokens_details": { "image_tokens": 1024, "text_tokens": 23 },
    "output_tokens": 196,
    "output_tokens_details": { "image_tokens": 196, "text_tokens": 0 },
    "total_tokens": 1243
  }
}
```

> ⚠️ 请求体必须是 **multipart/form-data**（用 `-F` 而不是 `-d`）。传 JSON 会返回 `failed to parse multipart form`。

---

## 2. 鉴权方式

| 项 | 值 |
|---|---|
| Header | `Authorization: Bearer <API 令牌>` |
| 兼容 Header | `x-api-key: <API 令牌>` / `api-key: <API 令牌>` |
| 令牌获取 | 登录控制台 →「令牌」页面创建 |
| 内容类型 | `multipart/form-data`（由 `-F` / FormData 自动生成，**不要手写**） |

**Base URL：`https://api.cxsee.com`**

---

## 3. 请求参数

全部以 **form-data 字段** 形式提交（不是 JSON body）：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | ✅ | **`gpt-image-2.5-flare`** |
| `prompt` | string | ✅ | 修改描述。**传空会报 400**（`field prompt is required`） |
| `image` | file | ✅ | 输入图片。缺失报 400 `image is required`。**支持 PNG / JPEG** |
| `image[]` | file[] | 否 | 多图输入（详见 3.3） |
| `mask` | file | 否 | 局部编辑蒙版。⚠️ **必须是 RGBA PNG**（详见 3.4） |
| `size` | string | 否 | 输出尺寸 `宽x高`，如 `"1024x1024"`；不传默认 `1254x1254` |
| `n` | integer | 否 | 输出张数，默认 1。**按张计费** |
| `quality` | string | 否 | `low` / `medium` / `high` / `auto`（默认由上游决定） |
| `response_format` | string | 否 | `"url"` 或 `"b64_json"`。⚠️ **不传默认 `b64_json`** |

### 3.1 关于 `image`

- 输入图片通过**文件上传**提交，不支持直接传图片 URL
- ⚠️ 传 JSON + `"image": "https://..."` 会直接失败：`failed to parse multipart form`
- 若图片本身在公网，请先下载到本地再作为文件上传
- 输入图尺寸**不决定**输出尺寸；输出尺寸由 `size` 参数控制（不传则 `1254x1254`）

### 3.2 关于 `size`

与文生图一致，`size` 是**唯一有效的尺寸控制方式**：

| 想要的画面 | 推荐写法 |
|---|---|
| 正方形 | `-F "size=1024x1024"` |
| 横版 | `-F "size=1536x1024"` |
| 竖版 | `-F "size=1024x1536"` |
| 不指定 | 省略该字段 → 输出 `1254x1254` |

> `aspect_ratio` / `resolution` 在本模型上同样**无效**，请勿使用。

### 3.3 多图输入（`image[]`）

需要模型同时参考多张图时，用重复字段名 `image[]`：

```bash
curl -X POST "https://api.cxsee.com/v1/images/edits" \
  -H "Authorization: Bearer <你的API令牌>" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=把这两张图的元素融合成一张海报" \
  -F "image[]=@photo1.png" \
  -F "image[]=@photo2.png" \
  -F "size=1024x1024" \
  -F "response_format=url"
```

- 实测 2 张输入可用，`usage.input_tokens_details.image_tokens` 会按张数累加（2 张 ≈ 2048）
- **多图输入不额外计费**（仍是 $0.16/张输出）
- 也可用单数 `image`（单张场景）；两者提交单个文件均可

### 3.4 局部编辑（`mask`）⚠️ 重要坑

`mask` 用于指定「只修改图片的某个区域」，但**对格式有硬性要求**：

| mask 格式 | 结果 |
|---|---|
| **RGBA PNG（带透明通道）** | ✅ 正常提交 |
| RGB PNG / JPEG（无 alpha 通道） | ❌ **失败**，返回 `503 The model service is temporarily unavailable` |

> ⚠️ 这是本文档最容易踩的坑：mask 格式不对时，**上游返回的是"服务暂不可用"而不是格式错误**，极易被误判为平台故障而反复重试。

生成 RGBA mask 的示例（Python）：

```python
from PIL import Image, ImageDraw

# 与输入图同尺寸，RGBA 模式
mask = Image.new("RGBA", (1024, 1024), (0, 0, 0, 255))
draw = ImageDraw.Draw(mask)
# 画要编辑的区域（此处示例：让某块区域 alpha=0 即透明 = 待编辑区）
draw.polygon([(270, 400), (475, 270), (680, 400)], fill=(0, 0, 0, 0))
mask.save("mask.png")   # 必须保存为 PNG 以保留 alpha 通道
```

调用：

```bash
curl -X POST "https://api.cxsee.com/v1/images/edits" \
  -H "Authorization: Bearer <你的API令牌>" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=把屋顶换成蓝色瓦片" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "size=1024x1024" \
  -F "response_format=url"
```

> mask 尺寸需与输入图一致；透明/白色区域的语义与 OpenAI gpt-image 一致（**透明区域为待编辑区域**）。

---

## 4. 返回字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `created` | int | 生成时间（Unix 秒） |
| `background` | string | 背景模式，如 `"opaque"` |
| `data[].url` | string | （`url` 模式）图片链接，**带签名、有效期 7 天** |
| `data[].b64_json` | string | （`b64_json` 模式）base64 编码图片 |
| `model` | string | 实际使用的模型名 |
| `moderation` | string | 内容审核标记（通常为空字符串） |
| `output_format` | string | 输出格式，如 `"png"` |
| `quality` | string | 本次实际使用的品质档 |
| `size` | string | 本次实际输出的像素尺寸 |
| `usage` | object | token 用量明细（**仅作统计，不参与计费**） |

**`usage` 在编辑场景下的特点：**

| 字段 | 说明 |
|---|---|
| `input_tokens` | 输入总 token |
| `input_tokens_details.image_tokens` | **输入图片折算的 token**（1024×1024 输入图 ≈ 1024；2 张 ≈ 2048） |
| `input_tokens_details.text_tokens` | 提示词 token（通常十几到几十） |
| `output_tokens` | 输出 token（出图约 200~2058） |

> 与文生图相比，本接口的 `image_tokens` **不为 0** —— 这正是「模型确实读取了你的输入图」的证据。

---

## 5. 计费说明

**按「输出张数」固定价计费**，与文生图同价：

| 模型 | 单价（USD / 张） |
|---|---|
| **`gpt-image-2.5-flare`** | **$0.16** |
| `gpt-image-2.5-flare-c` | $0.15 |

**实测确认：**

| 请求 | 扣费 quota | 金额 |
|---|---|---|
| `n=1`（基本图生图） | 80000 | $0.16 |
| `n=1` + `size=1024x1024` | 80000 | $0.16 |
| `n=1` + `quality=high` | 80000 | $0.16 |
| `n=1` + **2 张输入图** | 80000 | $0.16（多图输入不加价） |
| `n=2` | 160000 | $0.32 |
| 缺 `image`（参数错误） | 0 | 不扣费 |

- ⭐ 与文生图一致：**`size` 和 `quality` 不影响单价**，只有 `n` 影响
- 失败请求（`4xx` / `503`）**不扣费**
- 平台金额以美元展示（`$1 = 500000 quota`，即 $0.16 = 80000 quota）
- 可在控制台 →「用量日志」查看扣费明细

---

## 6. 使用建议与限制

| 项 | 建议 |
|---|---|
| 请求格式 | 必须 `multipart/form-data`；**不要**用 JSON |
| 图片上传 | 只支持文件上传，**不支持图片 URL** |
| mask | 必须 **RGBA PNG**，否则报 503 |
| 输出尺寸 | 用 `size` 控制；`aspect_ratio` / `resolution` 无效 |
| 返回格式 | 需要 HTTP 链接请**显式传** `response_format=url`，否则默认给 base64 |
| 客户端超时 | 实测单张 **16~30 秒**，建议超时设 **≥ 120 秒** |
| 图片链接有效期 | `url` 模式为**签名临时链接（7 天）**，长期使用请自行转存 |
| 并发建议 | 单账号并发 ≤ 5，避免上游限流 |
| 重试策略 | 遇 `503` 建议退避 5~10 秒重试；但**先确认参数（尤其 mask 格式）没问题**，否则会一直失败 |
| 内容安全 | 请遵守平台内容合规条款，勿上传违规 / 侵权素材 |

---

## 7. 各语言示例

### Python（requests）

```python
import requests, base64

url = "https://api.cxsee.com/v1/images/edits"
headers = {"Authorization": "Bearer <你的API令牌>"}

files = {
    "image": ("input.png", open("input.png", "rb"), "image/png"),
    # 需要局部编辑时加上（务必是 RGBA PNG）：
    # "mask": ("mask.png", open("mask.png", "rb"), "image/png"),
}
data = {
    "model": "gpt-image-2.5-flare",
    "prompt": "把房子的屋顶改成蓝色，天空加几朵白云",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url",     # 需要 base64 则填 "b64_json"
}

resp = requests.post(url, headers=headers, files=files, data=data, timeout=180)
resp.raise_for_status()
result = resp.json()

print("输出尺寸:", result.get("size"))
print("输入图 token:", result["usage"]["input_tokens_details"]["image_tokens"])

for i, item in enumerate(result["data"]):
    if "url" in item:
        print(f"图片{i}:", item["url"])
    else:
        with open(f"edited_{i}.png", "wb") as f:
            f.write(base64.b64decode(item["b64_json"]))
```

### Python（多图输入）

```python
files = [
    ("image[]", ("a.png", open("a.png", "rb"), "image/png")),
    ("image[]", ("b.png", open("b.png", "rb"), "image/png")),
]
data = {
    "model": "gpt-image-2.5-flare",
    "prompt": "把两张图的元素融合成一张海报",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url",
}
resp = requests.post(url, headers=headers, files=files, data=data, timeout=180)
```

### Node.js（axios + form-data）

```javascript
const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");

const form = new FormData();
form.append("model", "gpt-image-2.5-flare");
form.append("prompt", "把房子的屋顶改成蓝色，天空加几朵白云");
form.append("image", fs.createReadStream("input.png"));
form.append("size", "1024x1024");
form.append("n", "1");
form.append("response_format", "url");

const res = await axios.post(
  "https://api.cxsee.com/v1/images/edits",
  form,
  {
    headers: {
      Authorization: "Bearer <你的API令牌>",
      ...form.getHeaders(),      // 关键：带上 multipart boundary
    },
    timeout: 180000,
    maxBodyLength: Infinity,
  }
);

console.log("输出尺寸:", res.data.size);
res.data.data.forEach((item, i) => console.log(`图片${i}:`, item.url));
```

### Node.js（原生 fetch，Node 18+）

```javascript
import fs from "node:fs";

const form = new FormData();
form.append("model", "gpt-image-2.5-flare");
form.append("prompt", "把房子的屋顶改成蓝色");
form.append("image", new Blob([fs.readFileSync("input.png")], { type: "image/png" }), "input.png");
form.append("size", "1024x1024");
form.append("response_format", "url");

const resp = await fetch("https://api.cxsee.com/v1/images/edits", {
  method: "POST",
  headers: { Authorization: "Bearer <你的API令牌>" },  // 不要手动设 Content-Type
  body: form,
});

const result = await resp.json();
console.log(result.data[0].url);
```

---

## 8. 常见错误码

| HTTP | 报错信息 | 原因 / 处理 |
|---|---|---|
| 401 | 令牌缺失 / 无效 | 检查 `Authorization: Bearer` 头 |
| 400 | `field prompt is required` | `prompt` 不能为空 |
| 400 | `image is required` | 必须上传 `image` 文件 |
| 400 | `failed to parse multipart form` | 用了 JSON body；改用 `multipart/form-data`（`-F`） |
| 400 | `quality must be one of: auto, low, medium, high, xhigh, max` | 改用 `low` / `medium` / `high` / `auto`，**不要用 `hd`** |
| 402 | 余额不足 | 充值或更换高余令牌 |
| 429 | 触发限流 | 降低并发，稍后重试 |
| 500 / 503 | `The model service is temporarily unavailable.` | ①**先检查 mask 是否为 RGBA PNG**；②若参数无误则为上游临时抖动，退避 5~10 秒重试 |

> `4xx`` 参数错误与 `503` 失败均**不扣费**。

---

## 9. 与文生图的差异对照

| 项 | 文生图 `/v1/images/generations` | 图生图 `/v1/images/edits` |
|---|---|---|
| 请求体 | `application/json` | **`multipart/form-data`** |
| 输入图 | 不需要 | **必填** `image`（文件上传） |
| `prompt` | 必填（空报 `prompt is required`） | 必填（空报 `field prompt is required`） |
| 多图输入 | — | `image[]` 支持 |
| `mask` | — | 支持（**须 RGBA PNG**） |
| 返回额外字段 | — | `model`、`moderation` |
| `usage.image_tokens` | 恒为 0 | **为输入图折算值**（如 1024） |
| 单价 | $0.16 / 张 | $0.16 / 张（同价） |
| 实测耗时 | 16~55 秒 | 16~30 秒 |

---

*文档对应版本：gpt-image-2.5-flare 图生图（2026-09-12 实测校准）*

上一篇：GPT-Image-2.5-Flare 文生图下一篇：Gemini 绘画（nano-banana系列）