图片编辑（图生图、遮罩与多图参考）

/v1/images/edits 支持两种请求方式：

• multipart/form-data：上传本地原图、多张参考图和遮罩文件。
• application/json：引用可公开访问的 HTTPS 图片和遮罩。

接口

POST https://api.ezmodel.cloud/v1/images/edits
Authorization: Bearer YOUR_API_KEY

Multipart 参数

参数	类型	必填	说明
model	string	是	使用 gpt-image-2
prompt	string	是	期望的编辑结果，最长 32,000 字符
image	file	单图时是	单张原图
image[]	file[]	多图时是	多张参考图；重复提交该字段，最多 16 张
mask	file	否	与第一张原图尺寸相同、带 alpha 通道的 PNG 遮罩
n	integer	否	输出数量，范围 1–10，默认 1
size	string	否	auto、标准尺寸或合法自定义尺寸
quality	string	否	auto、low、medium、high
background	string	否	auto 或 opaque
output_format	string	否	png 或 jpeg
output_compression	integer	否	JPEG 压缩质量，范围 0–100
user	string	否	终端用户标识

输入图片支持 PNG、WebP 和 JPEG，每张不超过 50 MB。

单图编辑

curl https://api.ezmodel.cloud/v1/images/edits \
  -H "Authorization: Bearer $EZMODEL_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=把天空改成日落，并保持建筑结构不变' \
  -F 'image=@original.png' \
  -F 'quality=low' \
  -F 'n=1' \
  -F 'size=1024x1024'

多图参考

多张图片的顺序有意义，请在提示词中明确每张图的用途。

curl https://api.ezmodel.cloud/v1/images/edits \
  -H "Authorization: Bearer $EZMODEL_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=保留第一张图的主体和构图，采用第二张图的蓝色色彩风格' \
  -F 'image[]=@subject.png' \
  -F 'image[]=@style.png' \
  -F 'quality=low' \
  -F 'n=1'

遮罩编辑

遮罩必须是带 alpha 通道的 PNG，并与第一张原图尺寸一致。完全透明的区域会被编辑；不透明区域会被保留。遮罩文件需小于 4 MB。

curl https://api.ezmodel.cloud/v1/images/edits \
  -H "Authorization: Bearer $EZMODEL_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=只在透明遮罩区域添加一盏落地灯，其他区域保持不变' \
  -F 'image=@room.png' \
  -F 'mask=@mask.png' \
  -F 'quality=low'

JSON + HTTPS 参考素材

images 是对象数组，每个对象使用 image_url；mask 是一个使用 image_url 的对象。不要把 URL 直接写成字符串数组。

curl https://api.ezmodel.cloud/v1/images/edits \
  -H "Authorization: Bearer $EZMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把产品改成蓝色，仅编辑遮罩的透明区域，保留标签和构图",
    "images": [
      {
        "image_url": "https://example.com/assets/product.png"
      }
    ],
    "mask": {
      "image_url": "https://example.com/assets/mask.png"
    },
    "quality": "low",
    "n": 1
  }'

不使用遮罩时直接省略 mask。所有 URL 必须可公开下载，临时或签名 URL 应在请求完成前保持有效。遮罩 URL 指向的 PNG 同样必须带 alpha 通道，且与第一张参考图尺寸一致。

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.ezmodel.cloud/v1",
)

with open("original.png", "rb") as image:
    response = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="把天空改成日落，并保持建筑结构不变",
        quality="low",
        n=1,
    )

image_base64 = response.data[0].b64_json
print(image_base64[:80])

编辑响应与文生图相同，图片位于 data[].b64_json，usage.input_tokens_details.image_tokens 会记录输入图片令牌。