---
title: 图像编辑 API 指南：GPT Image 2 与 Nano Banana 2
description: "使用 GPT Image 2 或 Nano Banana 2 构建生产级图像编辑 API 工作流：参考图契约、请求与响应结构、成本演算、验证关卡与安全重试规则。"
url: https://apitoken.sale/zh/docs/learn/image-editing-api-guide
language: zh-CN
---

# 使用 GPT Image 2 或 Nano Banana 2 编辑图像

GPT Image 2 提供 multipart 编辑路由：输入 PNG、JPEG 或 WebP，输出单张 base64 PNG；Nano Banana 2 把参考图作为原生多模态输入——格式更多、数量更多、尺寸明确。应按流水线可验证的参考图契约选型，并以终态 usage 结算。

## 选择能满足参考图契约的路由

图像编辑是一种携带参考图作为计费输入、并在提示词中只允许一项变更的生成请求。一个 apiToken.sale 预付密钥即可接入两条生产编辑路由：GPT Image 2 走 OpenAI Images 编辑端点，接受 1–5 张 PNG、JPEG 或 WebP（每张 ≤50 MB），返回单张非流式 base64 PNG；Nano Banana 2（模型 gemini-3.1-flash-image）走原生 Gemini generateContent 路由，最多接受 14 张 PNG、JPEG、WEBP、HEIC 或 HEIF 参考图，以 inlineData 图像 part 返回。应按应用可验证的参考图契约选型，而不是看品牌偏好。

| 能力 | GPT Image 2 | Nano Banana 2 |
| --- | --- | --- |
| 路由 | POST /v1/images/edits（multipart） | 含 inlineData part 的 generateContent |
| 参考图 | 1–5 | 最多 14 |
| 输入文件 | PNG、JPEG、WebP；每张 ≤50 MB | PNG、JPEG、WEBP、HEIC、HEIF |
| 输出 | 单张非流式 base64 PNG | image inlineData part |
| 局部重绘 | POST /v1/responses image_generation（+ jpeg/webp、partial_images） | generateContent 上的 prompt + reference parts |
| 已发布控制 | background opaque 或 transparent、quality low、size 比例预设（auto/1:1/3:2/2:3/4:3/16:9/9:16） | 1K/2K/4K + 已发布宽高比 |

> 两种协议不可互换。按 OpenAI Images schema 编写的客户端无法解析 Gemini inlineData 响应。GPT Image 2 编辑接受 50 MB 以内的 PNG、JPEG 或 WebP，仍返回一张 PNG。应在设计阶段按资产类别固定路由；在重试循环中切换协议会破坏输出解析与成本归因。

## 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 及其他像素尺寸会被拒绝。

```
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")},
    }],
)
```

## Nano Banana 2 编辑：参考图即多模态输入

Nano Banana 2 没有独立的编辑端点。一次编辑就是普通的 generateContent 调用：parts 数组把指令文本与每张参考图一个 inline_data part 混合，最多 14 张受支持图像。由于参考图只是另一个 part，JPEG 或 WEBP 目录照片无需转换即可传入——当源图库不是 PNG 时，这能切实简化流水线。

```
curl https://router.apitoken.sale/v1beta/models/gemini-3.1-flash-image:generateContent \
  -H "x-goog-api-key: $APITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @edit-request.json

// edit-request.json
{
  "contents": [{
    "parts": [
      { "text": "Replace only the background with a neutral studio backdrop; keep the product untouched" },
      { "inline_data": { "mime_type": "image/jpeg", "data": "<BASE64 REFERENCE>" } }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }
  }
}
```

generationConfig 固定输出契约：responseModalities 为 TEXT 加 IMAGE，明确 imageSize 取 0.5K、1K、2K 或 4K，并选择已发布宽高比之一。响应自带 parts 数组——图像以带 MIME type 与 base64 payload 的 inlineData part 返回，旁边可能还有文本 part。最便宜的可用尺寸传 0.5K 或 512；订阅线路使用 512。

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

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

## 按已发布费率演算编辑成本

普通 B2C 账户下，两款模型都按官方 usage 总额的五折（50%）计费。GPT Image 2 按 token 结算：折扣后 fresh text input 为每 1M $2.50，fresh image input 为每 1M $4，image output 为每 1M $15；cached input 在折扣前先按 fresh 费率的四分之一确认。每附加一张参考图都是计费 image input，因此参考图数量既是质量控制，也是成本控制。

| 演算示例 | 计费内容 | 普通 B2C 合计 |
| --- | --- | --- |
| GPT Image 2 编辑报告 1,200 text-input、4,000 image-input 与 4,200 image-output token | (1,200 × $2.50 + 4,000 × $4 + 4,200 × $15) / 1M | 结算 $0.082 |
| Nano Banana 2 1K 编辑 | 固定 1,120 image-output token + 实测输入项 | $0.0336 图像输出 + 输入 |
| Nano Banana 2 4K 编辑 | 固定 2,520 image-output token + 实测输入项 | $0.0756 图像输出 + 输入 |

第一行的 token 数量是示例而非费率：GPT Image 2 的 output usage 随请求变化，只有终态 usage 具有权威性。Nano Banana 2 恰好相反——image output 项按尺寸固定（B2C 折扣后 1K 为 $0.0336，2K 为 $0.0504，4K 为 $0.0756），而 text input、参考图 image input 与可能的文本/思考输出仍是变量。编辑的输入成本通常高于纯提示词生成；当好的参考图提高验收率、消除重试时，这部分投入就能赚回来。

[构成编辑账单的各项 token 费率详解](/docs/learn/image-generation-api-pricing)

## 成本与重试纪律

- 只发送确实约束本次编辑的参考图；两条路由上每张都是计费 image input。
- 歧义超时后绝不要自动重放编辑——提供商可能已完成工作，盲目重试就是第二次付费渲染。先按 request ID 核对。
- 限制每个源资产的变体与尝试次数，让质量关卡终止循环；五折只把浪费减半，并不能消除浪费。
- 为图像编辑 worker 配置带终身消费上限的独立密钥，与实验分开，避免批量 bug 耗尽共享余额。
- 先估算再花钱：对 gemini-3.1-flash-image 调用 countTokens 可免费测量输入；通过 Google 或 GitHub 注册的新账户带有 $5 欢迎赠金，足以覆盖早期流水线测试。

## 常见问题

### 哪个 API 接受更多参考图？

Nano Banana 2 的 generateContent 路由最多接受 14 张受支持图像输入；GPT Image 2 编辑路由接受 1–5 张 PNG、JPEG 或 WebP（每张 ≤50 MB）。

### GPT Image 2 能直接编辑 JPEG 或 WEBP 参考图吗？

编辑接受 PNG、JPEG 或 WebP，每张不超过 50 MB。GIF、HEIC 及其他类型会被拒绝。输出仍是一张 PNG。若需要 HEIC/HEIF 或超过五张参考图，使用 Nano Banana 2。

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

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

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

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

### 两条路由的编辑响应分别是什么样？

GPT Image 2 返回单个 JSON 文档，data[0].b64_json 中是一张 base64 PNG。Nano Banana 2 返回 Gemini candidates 结构，图像是带 MIME type 与 base64 payload 的 inlineData part。两条路由都不提供托管 URL：需自行解码、验证并存储字节。

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

通过 Google 或 GitHub 注册即可获得 $5 欢迎赠金；用已发布的 low/auto 配置运行 GPT Image 2，并用 countTokens 在渲染图像前预估 Nano Banana 2 的输入。先用 1K 验证整条流水线，再考虑 2K 或 4K 输出。

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