图片编辑 API 参考

gpt-image-2 图片编辑 API 参考与在线调试 — 上传参考图（最多 16 张）+ 指令进行单图改图、多图融合或 mask 局部重绘

POST /v1/images/edits

图片编辑：根据指令编辑或融合参考图

cURL

curl --request POST \
  --url https://api.apiyi.com/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form model=gpt-image-2 \
  --form 'prompt=把图1的人物放进图2的场景，沿用图3的色彩风格' \
  --form 'image=<string>' \
  --form image.items='@example-file' \
  --form mask='@example-file'

200

{
  "created": 1776832476,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 1280,
    "output_tokens": 6240,
    "total_tokens": 7520
  }
}

右侧的交互式 Playground 支持直接上传本地图片。请在 Authorization 中填入你的 API Key（格式：Bearer sk-xxx），选择 image / mask 文件并填入 prompt、model 后一键发送即可。

场景说明：本页用于「基于一张或多张参考图改图 / 融合生成 / mask 局部重绘」。请求为 multipart/form-data 格式。如需纯文本生成图片，请使用 文生图接口。

🖥️ 浏览器 Playground 限制（重要）

本接口的响应包含纯 base64 字符串（数 MB 量级）。受浏览器渲染限制，右侧 Playground 在收到响应后可能弹出 请求时发生错误: unable to complete request ——实际请求已经成功，只是浏览器无法把这么长的 base64 显示出来。

推荐做法（小白零踩坑）：

• 直接复制下方”代码示例”中的 Python / Node.js / cURL 到本地运行，代码会自动 base64.b64decode 并把图片保存为本地文件。
• 如要在浏览器里试 Playground，用极小的参考图（< 50KB） 并把 size 设为最小档（如 1024x1024）、quality 改为 low。

⚠️ 关键差异（从 gpt-image-1.5 迁移注意）

• 不要传 input_fidelity —— gpt-image-2 强制启用高保真，传了会 400 报错
• 编辑请求的输入 token 明显更高 —— 因为参考图按 Vision 计费规则换算成大量 token，预算要留足
• background: transparent 不支持 —— 改用 opaque 或自行后处理
• 多图融合最多 16 张 —— image[] 字段重复传入，超过会报错

📎 多图融合顺序有意义

image[] 字段可重复传入多张参考图，顺序将作为 prompt 中「图1/图2/图3」的引用依据。建议在 prompt 中显式指代，例如：

把图1的人物放进图2的场景，沿用图3的色彩风格

推荐单张 ≤ 10MB，格式 png / jpg / webp。

​

代码示例

​

Python（OpenAI SDK · 单图编辑）

from openai import OpenAI
import base64

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1"
)

resp = client.images.edit(
    model="gpt-image-2",
    image=open("photo.png", "rb"),
    prompt="把背景换成海边黄昏，保留人物细节",
    size="1536x1024",
    quality="high"
)

# b64_json 是纯 base64（无前缀），需自己 decode
with open("edited.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

​

Python（OpenAI SDK · 多图融合）

resp = client.images.edit(
    model="gpt-image-2",
    image=[
        open("person.png", "rb"),
        open("scene.png", "rb"),
        open("style.png", "rb"),
    ],
    prompt="把图1人物放进图2场景，沿用图3的色彩风格，保持光线一致",
    size="1536x1024",
    quality="high"
)

with open("fused.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

​

cURL（多图融合）

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "prompt=把图1的人物放进图2的场景，保留图3的色彩风格" \
  -F "size=1536x1024" \
  -F "quality=high" \
  -F "image[]=@person.png" \
  -F "image[]=@scene.png" \
  -F "image[]=@style.png"

​

cURL（mask 局部重绘）

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "prompt=把天空换成粉色晚霞" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "image[]=@photo.png" \
  -F "mask=@mask.png" \
  | jq -r '.data[0].b64_json' | base64 -d > photo_edited.png

​

Node.js（原生 fetch + FormData · 多图融合）

import fs from 'node:fs';

const form = new FormData();
form.append('model', 'gpt-image-2');
form.append('prompt', '把图1的人物放进图2的场景');
form.append('size', '1536x1024');
form.append('quality', 'high');
form.append('image[]', new Blob([fs.readFileSync('./person.png')]), 'person.png');
form.append('image[]', new Blob([fs.readFileSync('./scene.png')]), 'scene.png');

const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer sk-your-api-key' },
    body: form
});

const { data } = await resp.json();
fs.writeFileSync('fused.png', Buffer.from(data[0].b64_json, 'base64'));

​

参数说明速查

字段	类型	必填	默认	说明
model	text	是	—	固定填 gpt-image-2
prompt	text	是	—	编辑 / 融合指令
image[]	file	是	—	参考图，可重复多次（最多 16 张）
mask	file	否	—	掩码图（仅对第一张 image 生效，要求带 alpha 通道）
size	text	否	auto	输出尺寸，同文生图
quality	text	否	auto	low / medium / high / auto
output_format	text	否	png	png / jpeg / webp
output_compression	text	否	—	0–100，仅 jpeg / webp 生效
background	text	否	auto	auto / opaque（不支持 transparent）

​

mask 局部重绘要求

• 与原图相同尺寸、相同格式，单张 ≤ 50MB
• 必须带 alpha 通道：透明区域（alpha=0）= 要重绘的部分，不透明区域 = 保留
• mask 仅对第一张 image 生效
• mask 作为「软引导」而非精确边界，模型可能在蒙版周围扩展 / 收敛

多轮迭代：把上一次的输出作为下一次的 image[] 输入，配合新的编辑指令，可逐步精调画面。每一轮都按 token 实计，预算时留意累计成本。

​

响应格式

{
    "created": 1776832476,
    "data": [
        {
            "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
        }
    ],
    "usage": {
        "input_tokens": 1280,
        "output_tokens": 6240,
        "total_tokens": 7520
    }
}

b64_json 字段是纯 base64，不含 data:image/...;base64, 前缀，与 gpt-image-2-all 不同。客户端需自行 decode 写文件，或在浏览器端拼前缀渲染。

编辑请求的 input_tokens 通常显著高于同尺寸文生图，原因是参考图按 Vision 计费规则换算。多图融合时输入 token 会随图片数量进一步增加。

授权

Authorization · string · header · 必填

在 API易控制台获取的 API Key

请求体

multipart/form-data

model · enum<string> · 默认值: gpt-image-2 · 必填

模型名称，固定为 gpt-image-2

可用选项: gpt-image-2

prompt · string · 必填

编辑/融合指令。多图场景可用「图1/图2/图3」指代 image 上传顺序

示例:

"把图1的人物放进图2的场景，沿用图3的色彩风格"

image · file[] · 必填

参考图，可重复多次（最多 16 张）。单图直接传一次，多图重复传同名 image 字段（例如 -F image=@a.png -F image=@b.png），按上传顺序对应 prompt 中的「图1/图2/...」。单张 ≤ 10MB，格式 png/jpg/webp

mask · file

掩码图（可选，仅对第一张 image 生效）。要求：

• 与原图相同尺寸、相同格式
• 必须带 alpha 通道（alpha=0 表示要重绘的区域，不透明区域保留）
• 单张 ≤ 50MB

size · string · 默认值: auto

输出尺寸（同文生图）。预设或满足约束的自定义尺寸

示例:

"1536x1024"

quality · enum<string> · 默认值: auto

画质档位

可用选项: auto, low, medium, high

output_format · enum<string> · 默认值: png

输出格式

可用选项: png, jpeg, webp

output_compression · integer

输出压缩率（0–100），仅 jpeg/webp 生效

必填范围: 0 <= x <= 100

background · enum<string> · 默认值: auto

背景模式。auto 或 opaque。不支持 transparent

可用选项: auto, opaque

响应

200

application/json

成功生成图片

created · integer

示例:

1776832476

data · object[]

生成结果数组（本模型单次返回 1 张）

Show child attributes

usage · object

本次调用 token 用量

Show child attributes