图片编辑

上传一张或多张图片,再用提示词说明要改什么,比如换背景、局部重绘、多图合成。接口兼容 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)

BASH
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)

BASH
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)

PYTHON
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[]:

BASH
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 数组:

JSON
{
  "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"}
BASH
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 输出组合
BASH
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
JSON
{
  "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 相关的参数错误是统一提示(如「请求参数暂不支持,请检查请求格式」),不会指出具体字段。

其余错误与重试建议同图片生成 · 错误,通用错误码见错误码。

相关文档