Images Edits

通过 multipart 文件或 JSON URL/Data URL 编辑图片，并支持 typed SSE。

最后更新: 2026-08-14

POST/v1/images/edits

根据图片、可选 mask 与提示词生成编辑结果。

参数	类型	要求	说明
`image / image[]`	file \| file[]	必填	multipart 的 PNG、JPEG 或 WebP 输入；可重复 image[] 上传多图。
`images[].image_url`	string	必填	JSON 输入数组；每个对象包含一个 HTTPS URL 或 Base64 Data URL。
`mask`	file \| { image_url: string }	可选	可选 PNG mask，尺寸必须与主图匹配；multipart 使用文件，JSON 使用 image_url 对象。
`prompt`	string	必填	编辑指令。
`model`	string	必填	已启用且具备 image_edit 能力的模型。
`n`	integer	可选	输出张数，默认 1。
`size`	string	可选	按张固定价格的尺寸维度，默认 auto。
`quality`	string	可选	按张固定价格的质量维度，默认 auto。
`stream / partial_images`	mixed	可选	开启 typed SSE 及预览图片。

curl --request POST 'https://api.easerouter.com/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'model=gpt-image-1' --form 'prompt=把天空改为晚霞' \
  --form 'image[]=@input.png;type=image/png' --form 'image[]=@reference.webp;type=image/webp' \
  --form 'mask=@mask.png;type=image/png' \
  --form 'n=1' --form 'size=1024x1024' --form 'quality=medium'

{
  "model": "gpt-image-1",
  "prompt": "把天空改为晚霞",
  "images": [
    { "image_url": "https://cdn.example.com/input.webp" },
    { "image_url": "data:image/png;base64,iVBORw0KGgo..." }
  ],
  "mask": { "image_url": "data:image/png;base64,iVBORw0KGgo..." },
  "n": 1, "size": "1024x1024", "quality": "medium"
}

from openai import OpenAI

client = OpenAI(base_url="https://api.easerouter.com/v1", api_key="YOUR_API_KEY")
with open("input.png", "rb") as image, open("mask.png", "rb") as mask:
    response = client.images.edit(model="gpt-image-1", image=image, mask=mask,
                                  prompt="把天空改为晚霞", size="1024x1024", quality="medium")

import OpenAI, { toFile } from 'openai'
import { readFile } from 'node:fs/promises'

const client = new OpenAI({ baseURL: 'https://api.easerouter.com/v1', apiKey: 'YOUR_API_KEY' })
const response = await client.images.edit({ model: 'gpt-image-1', prompt: '把天空改为晚霞',
  image: await toFile(await readFile('input.png'), 'input.png', { type: 'image/png' }),
  size: '1024x1024', quality: 'medium' })

event: image_edit.partial_image
data: {"type":"image_edit.partial_image","partial_image_index":0,"b64_json":"..."}

event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"..."}

image_edit.completed 是流的终止事件；服务端不会再追加 Chat 风格的结束哨兵。

限制与校验

单个 image 或 mask 最大 20 MB，解码后的输入合计最大 100 MB，完整 HTTP 请求体最大 140 MB。
服务按文件签名校验 PNG、JPEG 和 WebP，不信任扩展名或客户端 MIME；Base64 必须严格解码，Data URL 必须声明允许的图片 MIME。
HTTPS URL 下载执行 DNS/IP 重检、重定向限制和 SSRF 防护，拒绝 loopback、内网、link-local、凭据 URL 与非 HTTPS 地址。
JSON 中 file_id 当前不受支持；请使用 multipart 文件、HTTPS URL 或 Data URL。

计费、错误与重试

与生成接口相同，按 size + quality + 每张固定价格冻结和结算。SUBMIT_UNKNOWN 或 BILLING_PENDING 代表需要核对，超时后立即重试可能重复生成及收费。