GPT-Image 2 图像生成与编辑

GPT-Image 2 是无界模型云提供的图像生成与编辑模型，接口形态与 OpenAI 图像 API 兼容。它支持纯文本生成图像（文生图）、单图编辑（图生图），以及最多 16 张参考图的多图融合编辑。模型在中文提示词、版式控制和图文一致性上表现稳定，适合电商主图、海报、插画、产品图融合等场景。

概览

• 文生图：POST https://api.tos.run/v1/images/generations，application/json。
• 图生图 / 多图编辑：POST https://api.tos.run/v1/images/edits，multipart/form-data。
• model 固定为 gpt-image-2。
• 多图编辑是核心能力：用重复的 image[] 字段上传多张参考图，在提示词里用「图1 / 图2 / 图3」按上传顺序引用。

接口与 OpenAI Images API 兼容，已有 OpenAI 图像客户端只需切换 Base、Key 和 model 即可接入。需要注意的是，本网关只透传它真正支持的参数，其余 OpenAI 参数会被忽略——具体见下方「参数」与「OpenAI 兼容性」两节。

鉴权与 Base

• API 数据面 Base：https://api.tos.run/v1（浏览器控制台是 https://ai.tos.run，不要用作 API Base）
• 鉴权头：Authorization: Bearer $AI_TOS_API_KEY

API Key 在控制台创建，调用时通过 Authorization 头传入。生产环境请把 Key 放在服务端，不要暴露到浏览器。

文生图

向 /v1/images/generations 发送 JSON 请求，传入 model、prompt，以及可选的 size、quality 参数。文生图只生成单张图片，输出格式固定为上游默认的 PNG。

curl "https://api.tos.run/v1/images/generations" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "灰色桌面上的白色陶瓷马克杯，柔和自然光，电商主图风格",
    "size": "1024x1024",
    "quality": "auto"
  }'

图生图与多图编辑

向 /v1/images/edits 发送 multipart/form-data 请求。

公网图片 URL 快速验证

如果只是想快速验证链路，可以直接用 JSON 传公网可访问的图片 URL，不需要先下载到本地：

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "优化电商图排版和文字,模特发型改成微卷",
    "input_images": [
      "https://tos.cn-sh2.ufileos.com/public/image-curl-verify/2026-07-02/test_image-d9d3d81e4d88.png"
    ],
    "size": "1024x1024",
    "quality": "low"
  }'

input_images / images 支持公网 https:// 图片 URL、data URL 或纯 base64；生产集成建议仍使用自有 CDN，避免第三方图片链接失效。

单图编辑

只传一个 image 字段即可：

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product.png" \
  -F "prompt=把背景换成纯白电商主图背景，保留产品细节" \
  -F "size=1024x1024"

多图编辑（核心能力）

多张参考图用重复的 image[] 字段上传（OpenAI 数组式），最多 16 张，每张为 PNG / JPEG / WebP。上传顺序即引用顺序，在提示词里用「图1 / 图2 / 图3」指代对应的图片。

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image[]=@bag.png" \
  -F "image[]=@scarf.png" \
  -F "image[]=@model.png" \
  -F "prompt=让图3中的模特背上图1的手提包、围上图2的丝巾，输出整体街拍风格" \
  -F "size=1024x1536"

局部编辑（mask）

通过 mask 字段做局部重绘（inpainting）：只重绘 mask 的透明区域，保留不透明区域。mask 仅在 edits 接口的 multipart/form-data 下生效，网关会原样透传给上游（不做有损压缩，alpha 通道完整保留）。

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@room.png" \
  -F "mask=@room-mask.png" \
  -F "prompt=把遮罩区域替换为一扇落地窗" \
  -F "size=1024x1024"

• mask 是一张带 alpha 通道的 PNG：透明区 = 要重绘的区域，不透明区 = 保留原样。
• mask 作用于第一张参考图（即第一个 image / image[]）。
• 只支持 multipart（不走 JSON body）；默认路径与策略路由 / 故障转移的编辑路径都生效。
• 全部产线 gpt-image-2 号源（ap-image2 / pi-image2 / we-image2 / zm-image2 / codexpool）均支持 mask。

mask 尺寸与格式硬性要求

• mask 的宽高必须与第一张原图逐像素完全一致：差 1 像素也会报错。最稳的做法是从原图派生 mask（original.size），尺寸自动对齐。
• 必须是 RGBA 模式的 PNG，RGB / L / P 模式都会被拒（缺 alpha 通道会返回 invalid_image_file）。
• 单张 mask 文件应小于 4MB。
• 判定重绘区域的是 alpha 通道本身，不是肉眼可见的黑白。黑白蒙版要先 putalpha 转成 alpha 才有效。

程序化生成 mask（透明区 = 待重绘）：

from PIL import Image, ImageDraw

# 方式一：直接在原图尺寸上画一个透明矩形作为重绘区
mask = Image.new("RGBA", original.size, (255, 255, 255, 255))  # 不透明 = 保留
ImageDraw.Draw(mask).rectangle((300, 250, 750, 800), fill=(0, 0, 0, 0))  # 透明 = 重绘
mask.save("mask.png")

# 方式二：把已有的黑白蒙版转成 alpha（黑 0→重绘，白 255→保留）
bw = Image.open("mask_bw.png").convert("L")
rgba = Image.new("RGBA", bw.size, (255, 255, 255, 255))
rgba.putalpha(bw)
rgba.save("mask.png")

提示词要描述整幅画面

gpt-image 的 mask 是基于提示词的引导式编辑、走整图重生成，不是 DALL·E 2 那种硬像素合成。因此提示词不能只写待重绘的局部，应描述期望的完整画面，并明确写出哪些内容必须保持不变：

仅修改蒙版透明区域，将人物上衣替换成纯红色圆领棉质短袖；
保持人物脸部、发型、身体姿势与背景不变。

输出格式与张数

• output_format（默认 png，可选 png / jpeg / webp）仅在 edits 接口生效，用于指定返回图片的编码格式。
• n（生成张数）仅在 edits 接口、且 n > 1 时下发；不传或为 1 时返回单张。文生图不支持 n，始终返回单张。

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product.png" \
  -F "prompt=把背景换成纯白电商主图背景，保留产品细节" \
  -F "size=1024x1024" \
  -F "output_format=webp"

输入图压缩（edits 专属）

针对重型多图融合编辑，可通过请求头 x-input-image-compress: true 开启输入参考图的有损压缩，显著降低上传到上游、落盘的字节数，画质几乎无可见损失。

• 开启方式：请求头 x-input-image-compress: true（精确匹配 true，大小写不敏感）。
• 作用范围：仅作用于 edits 上传的参考图；对单张超过 200KB 的图片才生效，小图原样透传。
• 编码方式：用 sharp(libvips) 有损重编码到 q85 并保持原格式——JPEG → mozjpeg q85；PNG → 有损调色板(libimagequant) q85 + 最高压缩级；WebP → q85。gif / svg / 未知格式原样透传。
• 永不变大：若重编码后反而更大，则保留原图。
• 尽力而为：sharp 不可用或编码失败时原样透传，不会影响请求本身。

curl "https://api.tos.run/v1/images/edits" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "x-input-image-compress: true" \
  -F "model=gpt-image-2" \
  -F "image[]=@bag.png" \
  -F "image[]=@scarf.png" \
  -F "image[]=@model.png" \
  -F "prompt=让图3中的模特背上图1的手提包、围上图2的丝巾，输出整体街拍风格" \
  -F "size=1024x1536"

参数

下表列出本网关实际透传 / 生效的参数。未列出的 OpenAI 参数会被忽略，详见下方「OpenAI 兼容性」一节。

文生图接口（JSON body）发送 model / prompt / quality / size，外加扩展字段 aspectRatio / provider。编辑接口（multipart）发送 image / image[] / model / prompt / size / quality，外加 output_format 和 n。

尺寸说明

size 有两种用法：

1. 快速试图：传 1K / 2K / 4K，并在文生图时传 aspectRatio。
2. 指定请求画布：直接传表中的 宽x高。这是默认号源可稳定复现的规格；不必再传 aspectRatio。

下表是默认号源实际生效尺寸。表外显式尺寸会按比例对齐到最近规格；部分高级号源可能保留更多尺寸，但不应把该行为当作跨号源契约。

显式尺寸用于选择比例和档位，但最终返回像素仍取决于实际号源。需要固定交付尺寸时，请使用表内值、固定已验证的 provider，并在生成后读取返回图片的实际像素；quality 只影响画质、耗时与计费，不改变请求比例。

OpenAI 兼容性

本接口与 OpenAI Images API 兼容，从 OpenAI 迁移时注意以下参数本网关暂未透传 / 暂不支持，设置后会被静默忽略：

• output_compression：压缩输出图——本网关不支持。如需压缩，可用 edits 的 x-input-image-compress 压缩输入参考图（用途不同，见上文）。
• background（opaque / transparent / auto）：不支持，gpt-image-2 默认输出不透明背景。
• output_format：文生图接口不支持（始终返回上游默认的 PNG），仅在 edits 生效。
• n：文生图接口不支持（始终单张），仅 edits 且 n > 1 时生效。
• 面向调用方的 stream / partial_images：不支持，调用方始终收到一次性的完整 JSON 响应（详见下方「响应」）。

响应

响应始终是一次性的完整 JSON，没有面向调用方的流式（网关与上游之间可能内部走流式以规避 Cloudflare 524 超时，但这对调用方透明，你只会拿到完整 JSON body）。

data[] 中的每张图片以 b64_json（纯 base64）或 url（serve URL）返回；usage 给出用量信息。

{
  "created": 1717488000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 256,
    "output_tokens": 1568,
    "total_tokens": 1824,
    "generated_images": 1
  }
}

• b64_json 为纯 base64 字符串，落盘或在前端展示前需自行拼接 data:image/png;base64, 前缀。
• url 为带时效的 serve 链接，请尽快转存到自有存储。
• usage 包含 input_tokens（上游上报时透出）、output_tokens、total_tokens 与 generated_images。

异步任务 API（/api/jobs）

4K、多图融合、局部重绘等长耗时生成，建议用异步任务：一次提交拿到任务 id，再轮询结果，避免长连接在发版 / 超时时被打断。

异步与同步走的是同一条处理链路——同一套鉴权、路由、额度与计费中间件，同一套请求体解析与参数转换。异步端点接受与同步 /v1/images/* 完全相同的生成参数，并原样透传给上游，因此凡是同步支持的参数，异步都等价支持；同步不支持的（如 output_compression / background）异步同样不支持。这套异步协议对 gpt-image-2 与 Gemini（Nano Banana） 统一：提交 / 轮询 / 取消端点与响应结构一致，只把 model 换成对应模型即可。

完整参数

除 model / prompt / size / aspectRatio 外，异步提交还支持与同步一致的下列参数：

提交

POST https://api.tos.run/api/jobs。文生图与多图融合用 JSON，局部重绘 / 带参考图的编辑用 multipart/form-data：

# 文生图（OpenAI 形态）：多张 + 指定输出格式
curl "https://api.tos.run/api/jobs" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gpt-image-2", "prompt": "赛博朋克城市夜景", "size": "4K", "aspectRatio": "16:9" }'

# 局部重绘（mask）：multipart，参考图 + mask + 输出 webp
curl "https://api.tos.run/api/jobs" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@room.png" \
  -F "mask=@room-mask.png" \
  -F "prompt=把沙发换成布艺款，保留其余陈设" \
  -F "output_format=webp"

# 换成 Gemini：同一套端点，仅 model 不同；media_resolution 生效
curl "https://api.tos.run/api/jobs" \
  -H "Authorization: Bearer $AI_TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gemini-3-pro-image", "prompt": "高清城市夜景", "aspectRatio": "16:9", "media_resolution": "high" }'

提交返回任务对象（id / status / progress 等）；轮询、取消、列表与保留期（7 天）与 Nano Banana 异步任务 完全一致，此处不再赘述。完成后 outputs 给出可下载 URL（而非内联 base64）。

价格

按图片规格与画质档位整张计费，不再单独计入图像 token。实际价格以控制台展示为准，组织专属价格优先。

耗时与错误处理

图像生成与编辑耗时受质量和分辨率影响较大，请把客户端超时设到 ≥ 600s：

• auto（默认）：由模型按内容自动选择画质，耗时介于下列区间
• low：约 10–40s
• medium：约 30–90s
• high 或 2K / 4K 复杂编辑：3–5 分钟
• 多图编辑耗时更高，按最复杂场景预留超时

接入建议：

• 把 API Key 放在服务端，不要暴露到浏览器。
• 复杂、高分辨率编辑可能较慢，对瞬时网络错误（连接超时、5xx 网络抖动）可做有限次重试。
• 遇到「An error occurred while processing your request.」这类系统繁忙错误，应直接提示用户稍后再试，不要反复重试拉长整体超时。
• 返回 url 时请尽快将图片转存到自有存储，链接有时效性。