---
title: 图像编辑 API：GPT Image 模型
description: "构建 GPT Image 编辑流程：参考图、请求示例、成本测量与输出验证。"
url: https://apitoken.sale/zh/docs/learn/image-editing-api-guide
language: zh-CN
---

# 使用 GPT Image 2、Flare 或 Sunburst 编辑图像

GPT Image 模型通过 Images 编辑接口接受最多五张 PNG、JPEG 或 WebP 参考图。使用与生成相同的密钥和余额，发布前验证每个结果。

## 用 GPT Image 编辑参考图

GPT Image 2、GPT Image 2.5 Flare 与 GPT Image 2.5 Sunburst 使用相同的 OpenAI Images 接口、密钥和预付余额。Flare 适合较快的日常任务，Sunburst 侧重更精细的编辑。请按通过验收的结果比较模型。三者的已发布 token 费率相同。

POST /v1/images/edits 接受一至五张 PNG、JPEG 或 WebP 参考图，每张最大 50 MB，通过 image 或 image[] 传入。模型 ID 与生成相同。multipart mask 字段会被忽略，局部重绘请使用 Responses 的 image_generation 工具。验收前检查几何形状、文字和产品一致性。

## GPT Image 2 编辑：PNG、JPEG 或 WebP 输入，单张 base64 PNG 输出

编辑端点使用 multipart form data：model、prompt，以及每张参考图一个 image 字段。已发布配置为 background opaque 或 transparent、quality low，以及作为比例的 size（auto、1024x1024/1:1、1536x1024/3:2、1024x1536/2:3、4:3、16:9、9:16）。响应是单个 JSON，data 中一张 base64 PNG。2K/4K size 值引导宽高比，不保证对应的像素分辨率。

```
curl https://router.apitoken.sale/v1/images/edits \
  -H "Authorization: Bearer $APITOKEN_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Replace only the background with a neutral studio backdrop; keep the product untouched" \
  -F "image=@reference.png;type=image/png" \
  -F "background=opaque" \
  -F "quality=low" \
  -F "size=auto"
```

> 每张参考图重复字段名 image，或发送 image[]。/v1/images/edits 会忽略 multipart mask；局部重绘请用 Responses input_image_mask。

```
// Response (abridged): decode data[0].b64_json into a PNG file.
{
  "data": [
    { "b64_json": "<BASE64 PNG>" }
  ]
}
```

解码 payload 并不代表请求结束。把 request ID 与终态 usage 和源图、结果一起保存：PNG 字节大小不是计费公式，结算权威是终态 usage event，仪表板扣费也以它为核对依据。

## 局部重绘：用 Responses 蒙版，不是 Images 的 mask

POST /v1/images/edits 上的 multipart mask 字段会被忽略。此 ChatGPT 池不提供该 OpenAI Images 形态。若要只改图片的一部分——或从 GPT 文本模型调用 hosted image_generation——请调用 POST /v1/responses（Chat Completions 映射同一工具）：源 PNG 作为 input 中的 input_image，并添加 tools: [{type:"image_generation", …}]。蒙版将 input_image_mask.image_url 设为 data:image/png;base64,…。蒙版须与源图同尺寸。透明像素是修改区域，不透明保持不变。Responses 还转发 output_format jpeg/webp 与 partial_images 1..=3（SSE response.image_generation_call.partial_image）；background=transparent 改写为 opaque，input_fidelity 被丢弃。file_id 会失败——这里没有 Files API。结算按 image token；蒙版不是第二张参考图。独立的 POST /v1/images/* 仍只返回非流式 PNG。

```
import base64, os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["APITOKEN_API_KEY"],
    base_url="https://router.apitoken.sale/v1",
)
def png_url(path):
    return "data:image/png;base64," + base64.b64encode(Path(path).read_bytes()).decode()
response = client.responses.create(
    model="gpt-5.6-sol",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Change only the masked region."},
            {"type": "input_image", "image_url": png_url("photo.png")},
        ],
    }],
    tools=[{
        "type": "image_generation",
        "output_format": "webp",
        "partial_images": 2,
        "input_image_mask": {"image_url": png_url("mask.png")},
    }],
)
```

## 把编辑当作受验证的流水线运行

1. 在服务端规范并检查每张参考图：解码文件，确认 MIME type 受支持，在任何付费调用前拒绝空文件或超限 payload。
2. 编写编辑 brief，把不可变特征——产品几何形状、logo、标签文字——与唯一的指定变更分开；每次请求只改一处，故障才可诊断。
3. 从 data[].b64_json 解码每个结果，保存前验证文件。
4. 每个源资产只派发一个有界候选项；首个输出通过审核前，不要铺开付费变体。
5. 在任何下游环节看到交付图像之前，先验证格式、合理尺寸、产品一致性以及不存在禁止改动。
6. 把 request ID、终态 usage、prompt 版本、源图与结果一起持久化；这份记录既是回滚路径，也是成本归因依据。

## 按实测 token 用量制定预算

| 每百万 token 用量 | 官方 | 普通 B2C · 五折 |
| --- | --- | --- |
| 文本输入 | $5 | $2.50 |
| 缓存文本输入 | $1.25 | $0.625 |
| 图像输入 | $8 | $4 |
| 缓存图像输入 | $2 | $1 |
| 图像输出 | $30 | $15 |

例如，一次编辑使用 900 个新文本输入 token、1,200 个新图像输入 token 和 4,000 个图像输出 token，官方费用为 $0.1341，普通 B2C 为 $0.06705。这些 token 数仅为示例，并非每张图片的保证值。请用实际终态 usage 和对应请求扣费进行测量。

目录或批量任务的成本应为全部结算费用除以通过验收的图片数，也要计入未通过审核的付费输出。GPT Image 没有免费的 countTokens 估算器，请先付费测量少量样本，并在启动队列前设置消费上限。

## 成本与重试纪律

1. 选择 GPT Image 模型及少量典型提示词和参考图。
2. 设置消费上限，并在样本中使用 n=1、quality=low、size=auto。
3. 记录每个请求的最终 usage 与扣费，包括被拒结果。
4. 将结算费用除以验收图片数，用实测成本制定批量预算。

## 常见问题

### 编辑是否比纯提示词生成更贵？

编辑会增加计费 image input，因此可比编辑的输入成本通常更高；但当参考图提高验收率、消除重试时，每个验收资产的成本仍可能更低——应按验收资产的结算成本衡量，而不是按请求。

### 超时后重试编辑安全吗？

只有能证明前一次尝试未被接受时才安全。歧义超时可能掩盖已完成的提供商工作；应保留 request ID 并先核对，否则重试就是对同一任务的第二次付费渲染。

### 如何低成本测试编辑路由？

先用一张参考图及 n=1、quality=low、size=auto。扩大任务前检查返回尺寸与最终 usage。

### 可以发送哪些参考图？

向 /v1/images/edits 的 image 或 image[] 字段发送一至五张 PNG、JPEG 或 WebP，每张不超过 50 MB。

---
Get a key: https://apitoken.sale/register
More guides: https://apitoken.sale/zh/docs/learn