图片编辑
上传一张或多张图片,再用提示词说明要改什么,比如换背景、局部重绘、多图合成。接口兼容 OpenAI POST /v1/images/edits。纯文本生图请用图片生成。
| 项 | 值 |
|---|---|
| 方法与路径 | POST /v1/images/edits |
| 鉴权 | Authorization: Bearer YOUR_API_KEY |
| Content-Type | multipart/form-data(上传本地文件)或 application/json(引用 URL / base64) |
示例中的模型名只作演示。可用模型以
GET /v1/models为准。
快速示例
上传本地文件(multipart)
curl https://www.nextai-code.com/v1/images/edits \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
--max-time 600 \
-F 'model=gpt-image-2' \
-F 'prompt=把背景换成花园,保持人物和服装不变' \
-F '[email protected];type=image/png' \
-F 'output_format=png' \
-F 'n=1' \
-o image-response.json
cURL 会自动生成带 boundary 的 Content-Type,不要手动设置这个头。响应格式与图片生成相同,保存方式见图片生成 · 快速示例。
引用图片 URL(JSON)
curl https://www.nextai-code.com/v1/images/edits \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
--max-time 600 \
-d '{
"model": "gpt-image-2",
"prompt": "把背景换成花园,保持人物和服装不变",
"images": [{"image_url": "https://example.com/input.png"}],
"output_format": "png"
}' \
-o image-response.json
image_url 也可以是完整的 data:image/png;base64,... 字符串。URL 必须是公网可访问的地址。
Python(OpenAI SDK)
import base64, os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NEXTAI_API_KEY"],
base_url="https://www.nextai-code.com/v1",
timeout=600.0,
max_retries=0,
)
with open("input.png", "rb") as f:
response = client.images.edit(
model="gpt-image-2",
image=f,
prompt="把背景换成花园,保持人物和服装不变",
n=1,
)
for i, image in enumerate(response.data, start=1):
Path(f"edit-{i}.png").write_bytes(base64.b64decode(image.b64_json))
两种写法怎么选
| 写法 | 输入图片字段 | 适合 |
|---|---|---|
| multipart | image 或 image[] 文件字段,可重复 |
直接上传本地文件 |
| JSON(OpenAI 格式) | images 数组,每项 {"image_url": "..."} |
图片已有 URL / base64,或服务端脚本 |
OpenAI 格式里的 file_id 引用的是模型服务商侧的文件,平台不提供文件上传接口,请改用 URL 或 base64。Gemini 模型的 JSON 写法不同,见下文「Gemini 模型」。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 图片模型名 |
prompt |
string | 是 | 修改指令 |
image / image[] |
file | multipart 必填 | 输入图片,至少一个。多张图重复上传,image 与 image[] 两种字段名等价 |
images |
array | JSON 必填 | 输入图片引用,见上表 |
mask |
file / object | 否 | 蒙版,见下文 |
n |
integer | 否 | 输出张数,默认 1,上限 10。multipart 下必须是非负整数 |
size |
string | 否 | 输出尺寸,取值规则同图片生成 |
quality |
string | 否 | 同图片生成。GPT Image 省略时按 auto |
response_format |
string | 否 | 同图片生成 |
output_format |
string | 否 | 同图片生成 |
background |
string | 否 | 同图片生成 |
output_compression |
integer | 否 | 同图片生成 |
moderation |
string | 否 | 同图片生成 |
input_fidelity |
string | 否 | 对输入图的保真度,如 high / low,仅支持该字段的编辑模型有效 |
style / user |
string | 否 | 透传给模型服务商 |
stream |
boolean | 否 | multipart 下写字符串 true 才视为开启;不能与 async 同时开启 |
partial_images |
integer | 否 | 仅支持流式的模型有效 |
watermark |
boolean | 否 | multipart 下写 true / false |
async |
boolean | 否 | 平台异步开关,见异步任务与素材下载。multipart 下只接受可解析为布尔值的文本(如 true / false),否则返回 async 参数不合法,必须是 true 或 false |
多图与输出数量是两回事: 参考图张数由输入字段决定(受模型限制),输出张数只由 n 控制。
未列出的字段: 调用 OpenAI 系列模型时,multipart 中的其他文本字段和文件字段、JSON 中的其他字段(含嵌套对象)都会原样转发给模型服务商,是否生效取决于模型。
进阶用法
多张参考图
multipart 重复 image[]:
curl https://www.nextai-code.com/v1/images/edits \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-F 'model=gpt-image-2' \
-F 'prompt=把瓶子放在木托盘上,拍成商业产品图,柔和棚拍光' \
-F 'image[][email protected]' \
-F 'image[][email protected]' \
-F 'n=1'
JSON 写进同一个 images 数组:
{
"model": "gpt-image-2",
"prompt": "把瓶子放在木托盘上,拍成商业产品图",
"images": [
{"image_url": "https://example.com/bottle.png"},
{"image_url": "https://example.com/tray.png"}
]
}
蒙版(mask)
蒙版的透明区域表示要修改的部分,其余区域尽量保持不变。蒙版应与第一张输入图同尺寸。
- multipart:上传 PNG 文件
-F '[email protected];type=image/png' - JSON:
"mask": {"image_url": "https://example.com/mask.png"}
curl https://www.nextai-code.com/v1/images/edits \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-F 'model=gpt-image-2' \
-F 'prompt=在透明区域画一扇圆窗' \
-F '[email protected];type=image/png' \
-F '[email protected];type=image/png'
Gemini 模型不支持 mask。
标注层(markup,GPT Image 新一代模型)
markup 是 OpenAI 新增参数,multipart 文件字段或 JSON 字段都会原样转发,是否可用取决于模型。以下说明参考 OpenAI 官方文档:
- 给第一张输入图附加一层透明 PNG 标注(圈出、写字说明要改哪里),不要把标注合并进原图
- 标注层须含透明像素,方向校正后与第一张输入图同宽高;两者各不超过 16,777,216 像素,标注文件不超过 50 MB
- JSON 写法:
"markup": {"image_url": "..."};原图仍放在images - 不能与
mask、prompt_rewriter或 GIF 输出组合
curl https://www.nextai-code.com/v1/images/edits \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-F 'model=gpt-image-2' \
-F 'prompt=替换标注圈出的招牌文字,保持其他区域不变' \
-F '[email protected];type=image/png' \
-F '[email protected];type=image/png' \
-F 'complexity=low' \
-F 'output_format=png'
GPT Image 新一代模型的编辑接口也可以配合 output_format: "gif",用静态参考图生成 GIF;SVG 只能通过生成接口输出。
Gemini 模型
Gemini 图片模型通过本接口编辑时,输入写法与 OpenAI 略有不同:
| 写法 | 格式 |
|---|---|
| multipart(推荐) | image / image[] 文件,可多张 |
JSON image |
字符串或字符串数组,每项可为 data:image/...;base64,...、http(s):// URL,或不带前缀的纯 base64(按 JPEG 处理) |
JSON images |
[{"image_url": {"url": "..."}}](image_url 是对象),或字符串数组;不支持 file_id |
{
"model": "gemini-3.1-flash-image",
"prompt": "把这几样元素合成一张化妆品广告横幅,柔和棚拍光",
"images": [
{"image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}},
{"image_url": {"url": "https://example.com/item2.png"}}
],
"size": "16:9",
"quality": "hd",
"response_format": "b64_json"
}
参数限制与图片生成 · Gemini / Nano Banana 与 Imagen 相同(不支持 mask、stream、input_fidelity 等)。Imagen 模型不支持编辑。
提示:只给参考图和很短的提示词时,模型容易直接复刻原图。明确写出要「重新创作」及具体修改点效果更好。
响应
与图片生成相同:同步返回 data[],async: true 时返回 task_id。
错误
| 情况 | HTTP | 处理 |
|---|---|---|
multipart 中没有 image / image[] 文件 |
400 | 检查字段名与 @ 文件路径 |
multipart 的 n 不是非负整数,或大于 10 |
400 | 修正 n |
multipart 的 async 不是合法布尔值 |
400 | 写 true 或 false |
Gemini 编辑没有识别到任何图片,或使用了 file_id |
400 或 422 | 按 Gemini 写法提供图片 |
| Gemini 传入不支持的参数、模型不支持编辑(如 Imagen) | 422 或 400 | 移除参数或换用支持编辑的模型 |
Gemini 相关的参数错误是统一提示(如「请求参数暂不支持,请检查请求格式」),不会指出具体字段。
其余错误与重试建议同图片生成 · 错误,通用错误码见错误码。