图片编辑 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'

import requests

url = "https://api.apiyi.com/v1/images/edits"

files = {
    "image.items": ("example-file", open("example-file", "rb")),
    "mask": ("example-file", open("example-file", "rb"))
}
payload = {
    "model": "gpt-image-2",
    "prompt": "把图1的人物放进图2的场景，沿用图3的色彩风格",
    "image": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('model', 'gpt-image-2');
form.append('prompt', '把图1的人物放进图2的场景，沿用图3的色彩风格');
form.append('image', '<string>');
form.append('image.items', '{
  "fileName": "example-file"
}');
form.append('mask', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.apiyi.com/v1/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apiyi.com/v1/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\n把图1的人物放进图2的场景，沿用图3的色彩风格\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apiyi.com/v1/images/edits"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\n把图1的人物放进图2的场景，沿用图3的色彩风格\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/edits")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\n把图1的人物放进图2的场景，沿用图3的色彩风格\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\n把图1的人物放进图2的场景，沿用图3的色彩风格\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

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的色彩风格

单张文件上限 50MB（multipart 文件上传），格式 png / jpg / webp；实践中建议先压到 1.5MB 以内再上传（详见下方「上传大小限制速查」）。

​

代码示例

​

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）

quality 不要传旧版 DALL·E 的 standard / hd。 只接受 low / medium / high / auto 四个官方枚举值。旧值在不同后端渠道下行为不一致：有时直接 400 报错（invalid_value），有时被静默忽略、按 auto 档跑出结果（费用不可控）。请始终显式传四个官方值之一。

​

上传大小限制速查

项目	限制	说明
参考图数量	最多 16 张	image[] 字段重复传入
单张图片（multipart 文件上传）	每张小于 50MB	支持 png / jpg / webp
单张图片（base64 data URL 方式）	字段长度约 20MiB	这是 URL/base64 字符串字段的长度限制（schema maxLength: 20971520），不等同于 multipart 文件上传的 50MB 上限；base64 编码会膨胀约 1/3，实际原图建议控制在 15MB 以内
mask 文件	PNG 且小于 4MB	须与原图相同尺寸、带 alpha 通道

总请求体积别顶满：虽然单图上限 50MB、最多 16 张，但多张大图同时接近上限时，单个请求体会非常大，容易在网关 / CDN / 超时层面失败。实践中建议每张先压到 1.5MB 以内（JPEG 质量 80-90），成功率和出图速度都会明显更好——输出画质与输入图体积无关。

​

参考图格式要求与预处理

/v1/images/edits 只接受 png / jpg / webp 三种标准格式。如果收到下面这个 400：

{
  "error": {
    "message": "Invalid image file or mode for image 1, please check your image file. ...",
    "type": "shell_api_error",
    "code": "invalid_image_file"
  }
}

大概率是参考图并非标准 JPEG/PNG。最常见的坑是手机原拍照片的 MPO 格式（Multi-Picture Object，多帧 JPEG 容器）：华为 Mate 系列等机型直出的 .jpg 内嵌 HDR 增益图副帧，实为 MPO。这类文件的文件头同为 FFD8，扩展名和 file 命令都显示 JPEG，肉眼无法分辨，只有按帧解析（如 Pillow）才能识别。报错里的「image 1」指第 N 张参考图（序号从 1 开始），可按序号定位问题图。

2026-07 实测：MPO 图 5 次上传全部 400；同一批图重编码为标准 JPEG/PNG 后，保持 3072×4096 原分辨率上传全部成功——问题出在格式，不在尺寸/体积。该错误在入口校验阶段快速返回（约 4 秒），不计费。

判别与修复：Image.open(f).format 返回 "MPO" 即需转换。上传链路统一做一次重编码即可，顺带兼容 HEIC 等其它手机格式：

from PIL import Image
import io

def normalize_image(path: str) -> bytes:
    """手机图片（MPO/HDR 多帧等）转标准 JPEG，通过 edits 格式校验"""
    im = Image.open(path)
    im.load()                      # MPO 只取第一帧（全尺寸主图）
    if im.mode not in ("RGB", "RGBA"):
        im = im.convert("RGB")
    out = io.BytesIO()
    im.save(out, format="JPEG", quality=92)   # 或 format="PNG"
    return out.getvalue()

业务是「用户上传实拍图」的场景（家装效果图、商品实拍等），建议在服务端上传链路统一重编码，而不是逐张排查——手机 HDR 照片会持续出现。更多输入图片处理技巧见 图片 API 调用须知与最佳实践。

​

mask 局部重绘要求

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

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

​

响应格式

{
    "created": 1776832476,
    "data": [
        {
            "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
        }
    ],
    "usage": {
        "input_tokens": 848,
        "input_tokens_details": {
            "image_tokens": 832,
            "text_tokens": 16
        },
        "output_tokens": 196,
        "output_tokens_details": {
            "image_tokens": 196,
            "text_tokens": 0
        },
        "total_tokens": 1044
    }
}

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

编辑请求的 input_tokens 通常显著高于同尺寸文生图，原因是参考图按 Vision 计费规则换算——具体消耗多少可以直接读 usage.input_tokens_details.image_tokens，与文本部分（text_tokens）是分开计的。多图融合时 image_tokens 会随参考图数量严格线性增加（2026-07 实测：4 张 1024² = 4 × 1024 tokens），量化数据见 多图输入的价格影响。详细字段说明见 概览页「如何查看每次调用的真实 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/...」。multipart 文件上传单张小于 50MB，格式 png/jpg/webp；实践建议压到 1.5MB 以内

mask · file

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

• 与原图相同尺寸
• PNG 格式且小于 4MB
• 必须带 alpha 通道（alpha=0 表示要重绘的区域，不透明区域保留）

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