跳转到主要内容
POST
/
v1
/
images
/
edits
图片编辑：根据指令编辑或融合参考图
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 mask='@example-file' \
  --form size=1536x1024 \
  --form quality=auto \
  --form output_format=png \
  --form output_compression=50 \
  --form background=auto \
  --form image[].items='@example-file'
{
  "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 格式。如需纯文本生成图片，请使用 文生图接口。
⚠️ 关键差异（从 gpt-image-1.5 迁移注意）
  • 不要传 input_fidelity —— gpt-image-2 强制启用高保真，传了会 400 报错
  • 编辑请求的输入 token 明显更高 —— 因为参考图按 Vision 计费规则换算成大量 token，预算要留足
  • background: transparent 不支持 —— 改用 opaque 或自行后处理
  • 多图融合最多 5 张 —— 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[][email protected]" \
  -F "image[][email protected]" \
  -F "image[][email protected]"

​
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[][email protected]" \
  -F "[email protected]" \
  | 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'));

​
参数说明速查

字段类型必填默认说明
modeltext是—固定填 gpt-image-2
prompttext是—编辑 / 融合指令
image[]file是—参考图，可重复多次（最多 5 张）
maskfile否—掩码图（仅对第一张 image 生效，要求带 alpha 通道）
sizetext否auto输出尺寸，同文生图
qualitytext否autolow / medium / high / auto
output_formattext否pngpng / jpeg / webp
output_compressiontext否—0–100，仅 jpeg / webp 生效
backgroundtext否autoauto / 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[]
必填

参考图，可重复多次（最多 5 张）。单张 ≤ 10MB，格式 png/jpg/webp

Maximum array length: 5
​
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

响应

成功生成图片

​
created
integer
示例:

1776832476

​
data
object[]

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

​
usage
object

本次调用 token 用量