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 请求。

单图编辑

只传一个 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。

输出格式与张数

• 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 既可以传一个尺寸档位（1K / 2K / 4K）配合文生图的 aspectRatio，也可以直接传显式的 宽x高。任何值都会被对齐（snap）到 gpt-image-2 支持的最接近像素尺寸。常用预设：

• 1024x1024、1536x1024、1024x1536
• 2048x2048
• 3840x2160、2160x3840

也支持自定义尺寸，建议满足：最长边 ≤ 3840、宽高均为 16 的倍数。竖版 3:4 常用 1728x2304。

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。

价格

按图片规格与画质档位（低 / 中 / 高）整张计费，不再单独计入图像 token；1K 与 2K 同价，4K 价格翻倍。

不传 quality（即 auto，由模型自动选择画质）时按对应规格的「高」档（基准价）计费。

实际价格以控制台展示为准，组织专属价格优先。

耗时与错误处理

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

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

接入建议：

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