跳到主要内容
API 参考/Images/图片编辑

编辑图片

POST/v1/images/edits

通过 OpenAI 兼容 Images API 调用 gpt-image-2，基于输入图片和编辑指令生成新的图片。

认证​

通过 Bearer Token 认证。图片编辑请求使用 multipart/form-data。

Authorizationstring必填

API Key，格式为 Bearer YOUR_API_KEY。

默认值：-
Content-Typestring必填

图片编辑请求使用 multipart/form-data。

默认值：multipart/form-data
Acceptstring可选

建议指定为 application/json。

默认值：application/json
Request-Idstring可选

客户侧生成的唯一请求标识，用于追踪和排查。

默认值：-

请求​

POST /v1/images/edits

modelstring必填

固定传 gpt-image-2。

默认值：gpt-image-2
imagefile | file[]必填

输入图片，支持 PNG、WebP、JPG。可传多张参考图，curl 中使用 image[] 上传多图。

默认值：-
promptstring必填

图片编辑指令，说明需要保持、替换、补全或重绘的内容。

默认值：-
maskfile可选

蒙版图片。需与第一张 image 格式和尺寸一致，并包含 alpha 通道。

默认值：-
sizestring可选

输出尺寸，支持 auto 和符合约束的常用尺寸。

默认值：auto
qualitystring可选

图片质量：low、medium、high 或 auto。

默认值：auto
output_formatstring可选

输出格式：png、jpeg 或 webp。

默认值：png
output_compressioninteger可选

JPEG/WebP 压缩等级，取值 0 到 100。

默认值：100
moderationstring可选

图片安全过滤强度：auto 或 low。

默认值：auto

保存和解码响应​

图片编辑响应中的 b64_json 可能较长。示例中先使用 -o response.json 保存完整响应，再通过 jq 和 base64 --decode 解码为图片文件，避免长 Base64 在终端输出或管道中被截断。

响应​

响应返回 Base64 图片数据和本次编辑使用的实际配置。

createdinteger必填

创建时间，Unix 时间戳。

默认值：-
backgroundstring可选

实际使用的背景模式。

默认值：-
output_formatstring可选

实际输出格式。

默认值：-
qualitystring可选

实际图片质量。

默认值：-
sizestring可选

实际输出尺寸。

默认值：-
dataarray必填

图片结果列表。

默认值：-
data[].b64_jsonstring可选

Base64 编码后的图片数据。

默认值：-
usageobject可选

图片编辑 Token 用量统计。

默认值：-

尺寸约束​

自定义尺寸通常需要满足：最长边不超过 3840px、宽高为 16px 的倍数、长短边比例不超过 3:1，并处于模型允许的总像素范围内。

错误​

状态码说明
400请求体字段错误、图片文件格式错误、尺寸不支持或蒙版不合法
401API Key 缺失或无效
403当前账户无权调用该模型
429请求超过速率限制
500 / 503平台或上游模型服务异常

相关指南​