OpenAI GPT Image 图生图 (i2i)

POST /v1/images/edits

Auth: {'type': 'bearer', 'description': '通过 `Authorization: Bearer sk-xxx` 提供 API Key'}

基于现有图片生成新图 (图生图 / image-to-image). 跟 [`/v1/images/generations`](./openai-gpt-image) (文生图) 不同, 本端点要求客户以 `multipart/form-data` 上传图像文件 + 文本编辑指令. ## 协议要点 | 维度 | 文生图 `/v1/images/generations` | 图生图 `/v1/images/edits` (本端点) | |---|---|---| | Content-Type | `application/json` | **`multipart/form-data`** | | 必填字段 | `model` + `prompt` | `model` + `prompt` + **`image` (文件)** | | 多图 | — | `image[]` 重复字段名 (部分模型支持) | | 局部编辑 | — | `mask` 可选 (透明区域为编辑目标) | ## 模型范围仅适用于 `gpt-image-*` 系列与 `dall-e-2`. 其他厂商的图生图能力 (如 Seedream / Qwen-Image-Edit) 请走 [`/v1/images/generations`](./openai-gpt-image) 端点的 JSON 协议 (上游协议是单 endpoint 设计). ## SDK 示例 (OpenAI Python SDK) ```python from openai import OpenAI client = OpenAI(api_key="sk-xxx", base_url="https://api.router.ai/v1") # 单图基础 resp = client.images.edit( image=open("photo.png", "rb"), prompt="把背景换成赛博朋克霓虹街道", model="gpt-image-2", size="1024x1024", ) # 局部编辑 (含 mask) resp = client.images.edit( image=open("portrait.png", "rb"), mask=open("mask.png", "rb"), # 蒙版透明区域 = 编辑目标 prompt="把蒙版区域替换为蓝天白云", model="gpt-image-2", ) ```

Request body

`image`	file (binary)	required	原始图像文件 (PNG / JPEG / WebP). 单张时字段名为 `image`; 多张参考图请重复使用字段名 `image[]` (部分模型支持多图输入)
`model`	string	required	图像模型 ID (如 `gpt-image-2` (推荐) / `gpt-image-1` / `dall-e-2`)
`prompt`	string	required	编辑指令文本; 描述越具体生成质量越高 (支持中英文)
`mask`	file (binary)		蒙版图像 (PNG; 透明区域为编辑目标). 仅部分模型支持局部编辑模式
`n`	integer		生成图片数量
`size`	string		图像尺寸 (宽×高). i2i 端点 (`/v1/images/edits`) 不支持 2K / 4K, 仅官方明文挡位: `gpt-image-1 / gpt-image-2` → `1024x1024` / `1024x1536` / `1536x1024`; `dall-e-2` → `256x256` / `512x512` / `1024x1024`. 需要 2K / 4K 高分辨率请走 t2i 端点 `/v1/images/generations` (gpt-image-2 支持 freeform 自定义, 16 倍数 / ≤3840px / 长短比 ≤3:1)
`quality`	string		质量档位. `low/medium/high` 是原生三档; `standard/hd` 是 DALL-E 兼容 alias
`response_format`	string		返回格式. `gpt-image-*` 始终返 `b64_json`; `url` 仅 DALL-E 系列生效
`output_format`	string		输出图像编码格式 (仅 `gpt-image-*` 支持)
`background`	string		背景类型; `transparent` 需配合 `output_format=png` 或 `webp`
`user`	string		客户端可选传入的最终用户标识 (用于上游滥用检测)

Responses

200 — 成功返回编辑后的图像 (含 base64). usage.input_tokens_details.image_tokens 反映输入图像消耗的视觉 token (跟文生图差异点)
400 — 请求参数错误 (mask 尺寸跟 image 不匹配 / 不支持的图像格式 / model 不支持 mask 等)
402 — 余额不足

Example

# 单图图生图
curl https://api.router.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F image="@photo.png" \
  -F model="gpt-image-2" \
  -F prompt="把背景换成赛博朋克霓虹街道, 保留人物主体不变" \
  -F size="1024x1024" \
  -F quality="high" \
  -F n=1

# 多图参考 (部分模型支持; image[] 重复字段名上传多张)
curl https://api.router.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F model="gpt-image-2" \
  -F prompt="把这两张照片的主体合并到一张图里, 保留各自风格"

# 局部编辑 (mask 蒙版, 透明区域 = 编辑目标)
curl https://api.router.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F image="@portrait.png" \
  -F mask="@mask.png" \
  -F model="gpt-image-2" \
  -F prompt="把蒙版区域替换为蓝天白云" \
  -F size="1024x1024"

API reference