图像编辑接口导读
把一张图加上文本指令送进去，拿回编辑后的图。和 /v1/images/generations 的区别在于：这个端点必须带输入图，输出是对原图的修改而不是从零生成。
POST/v1/images/edits
端点签名与 OpenAI 官方 /v1/images/edits 一致，所以你可以直接用 OpenAI SDK 切到 https://api.therouter.ai/v1 上来调。请求体是 multipart/form-data， 包含输入图片、prompt、可选 mask、size、quality 等字段。
支持的模型
一个模型能用于编辑的判定标准是：architecture.input_modalities 包含 image， 且 capabilities 包含 image_edit。 以线上 /v1/models 返回为准。
openai/gpt-image-2— 走 OpenRouter， 60–180 秒，quality=low约 $0.006 / 张。openai/gpt-image-1.5/openai/gpt-image-1— 走 OpenAI 直连， 质量稳定，quality=low约 $0.009–0.011 / 张。black-forest-labs/flux-kontext-pro/flux-kontext-max/flux-kontext-dev— 走 SiliconFlow， 按张收费 $0.015–0.08。Kontext 系列对原图构图保留得很好。qwen/qwen-image-edit— 走 SiliconFlow， $0.04 / 张。基于 20B Qwen-Image，特别擅长编辑图中的文字。
实时模型清单
以上列表是手工维护的；权威清单以
/v1/models 实时返回为准。 只要某个模型的 architecture.features 包含 image_edit，就能用本端点编辑。关键字段
| Name | Type | Required | Description |
|---|---|---|---|
model | string | Required | 标准模型别名 brand/model；模型必须声明 image_edit 能力。 |
image | file | Required | 要编辑的源图，PNG/JPEG/WebP，建议 ≤ 4 MB 且 ≥ 256×256。 |
prompt | string | Required | 编辑指令文本。指令越具体（指明区域、风格、保留元素）效果越好。 |
mask | file | 可选蒙版图（与 image 同尺寸）。不透明区域是要编辑的部分，透明区域保留。建议带 alpha 通道的 PNG。 | |
size | string | 输出尺寸，例如 1024x1024、1024x1536、1536x1024 或 auto。 | |
quality | string | low | medium | high | auto。质量档位差异显著影响价格——批量迭代用 low。 | |
n | integer | 目前只支持 n=1。要多张就并发多请求。 |
最小可跑示例（curl）
bash
curl -X POST https://api.therouter.ai/v1/images/edits \
-H "Authorization: Bearer $THEROUTER_API_KEY" \
-F "model=openai/gpt-image-2" \
-F "prompt=把整个画面改成水彩画风格，构图保持不变" \
-F "size=1024x1024" \
-F "quality=low" \
-F "image=@input.png" \
-o response.json
# 把编辑后的图解码出来
jq -r '.data[0].b64_json' response.json | base64 -d > edited.png行为差异需要注意
- 响应
model字段一律回显标准别名（如openai/gpt-image-2）， 不会暴露上游真实路径或具体版本号。 - 一次编辑动辄 60–180 秒，客户端超时建议设到 5 分钟以上。Gateway 这边对 upstream 的等待上限是 5 分钟。
- 带
mask时，gateway 会尽可能转换成上游模型的原生 mask 格式； 上游如果不支持 mask（例如走 chat-completions 的 OpenRouter 路径）， 会作为第二张图附带一段 mask 指令文本一起发出。 n > 1会被直接拒掉。要多张就发并发请求，配合不同 prompt 或 seed。- 计费同时按 token（prompt + 推理 token）和按张图收费；批量迭代请用
quality=low。
和 /v1/images/generations 的区别
没有输入图、只想从文本生图就用 /v1/images/generations。 有要修改的源图就用本端点。两条路径返回结构一致（都是 data[0].b64_json），客户端解码代码可以共用。