Skip to Content
goldflow.cc 文档
图片系列OpenAI Images

编辑图像

POST
/v1/images/edits

OpenAI Images API 兼容的图像编辑接口。默认同步返回编辑后的图片结果;如需异步提交,在请求 URL 上携带 ?async=true,接口会返回图片任务 ID,可通过 /v1/tasks/{id} 查询结果。 GPT Image 2.5 / 2.6 支持 JSON images 引用数组,或 multipart image / image[] 文件上传;输入图片支持 PNG、JPEG、WebP,最多 16 张。 markup 是单独上传的透明 PNG 标注层,与 mask 互斥。GPT Image 2.6 可输出 GIF;编辑接口不支持 SVG 输出或 SVG 输入。 stream=true 时返回 image_edit.partial_image 和 image_edit.completed SSE 事件;GIF 不支持流式输出。 官方参数说明:https://developers.openai.com/api/reference/resources/images/methods/edit 。

Authorization

bearerAuth
headerAuthorizationBearer <API key>

使用 Authorization Bearer API Key 进行鉴权。

Query Parameters

async?boolean

是否异步提交。

Defaultfalse

Request Body

  1. body

输入图片为 PNG、JPEG、WebP,每张小于 50 MB,最多 16 张;SVG 不是支持的输入格式。 mask 指定编辑区域,markup 提供可见标注,两者不可同时使用;markup 也不可与 prompt_rewriter 同用。 input_fidelity 是其他 GPT Image 型号的参数,此处的 2.5 / 2.6 请求不需要设置。

model*string
Value in"gpt-image-2.5-sunburst""gpt-image-2.5-sunburst-2026-09-08""gpt-image-2.5-flare""gpt-image-2.5-flare-2026-09-08""gpt-image-2.6-sunburst""gpt-image-2.6-flare"
prompt*string

描述生成内容或编辑要求;GIF 提示词应说明动作和循环方式。

Length1 <= length <= 32000
n?|

输出图片数量;GPT Image 2.6 的 GIF 按动画数量计,SVG 必须为 1。

Range1 <= value <= 10
Default1
size?|

auto 或 WIDTHxHEIGHT,例如 1024x1024、1536x1024、1024x1536、1536x864。 自定义静态尺寸的宽高为 16 的倍数,宽高比介于 1:3 与 3:1。 GPT Image 2.5 的单边不超过 3840,总像素为 655360–8294400;超过 2560x1440 的分辨率属于实验支持。 GPT Image 2.6 还须满足所选模型当前的像素总量和边长限制,不沿用 2.5 的数值上限。 GPT Image 2.6 GIF 的 size 是每帧尺寸:宽高为正数且为 16 的倍数,并与 frame_count、n 一起满足模型的动画像素预算; 不套用静态图片的总像素下限,可使用 auto 自动选取。

Match^(auto|[1-9][0-9]*x[1-9][0-9]*)$
Default"auto"
quality?|

GPT Image 2.5 / 2.6 的渲染质量;2.6 输出 SVG 时控制用于矢量化的参考图质量。

Default"auto"
Value in"auto""low""medium""high""xhigh""max"null
complexity?|

GPT Image 2.6 的图像规划计算量,与 quality 独立;SVG 时控制参考图,不控制 SVG 作者的 reasoning。

Default"high"
Value in"low""medium""high"null
background?|

背景模式。透明位图使用 png 或 webp 输出;GPT Image 2.6 的 SVG 也支持 transparent。

Default"auto"
Value in"auto""opaque""transparent"null
output_compression?|

JPEG / WebP 输出压缩参数;GPT Image 2.6 的 GIF 和 SVG 不支持自定义压缩。

Range0 <= value <= 100
Default100
frame_count?|

GPT Image 2.6 GIF 的帧数,仅用于 output_format=gif。

Range2 <= value <= 16
Default9
frame_duration_ms?|

GPT Image 2.6 GIF 每帧时长,单位毫秒;编码时舍入到最接近的 10 ms,仅用于 output_format=gif。

Range20 <= value <= 2000
Default200
stream?|

启用 SSE 返回预览和最终图像;GPT Image 2.6 的 GIF / SVG 不支持流式输出。

Defaultfalse
partial_images?|

流式输出中最多返回的中间预览图数量。0 表示只返回最终图;最终图提前完成时,实际预览数量可能更少。 GPT Image 2.6 的 GIF / SVG 不支持中间预览图。以最终事件的 usage 读取用量。

Range0 <= value <= 3
Default0
safety_identifier?|

稳定的终端用户安全标识,建议使用哈希。非空值优先于 user;省略、null 或空字符串时回退到 user。

Lengthlength <= 128
user?stringDeprecated

已废弃的终端用户标识;仅在 safety_identifier 省略、null 或为空时作为回退值。

output_format?|

编辑输出支持 PNG / JPEG / WebP;GPT Image 2.6 还支持 GIF。编辑接口不支持 SVG。

Default"png"
Value in"png""jpeg""webp""gif"null
images*array<|>

原始图片引用;首张图片是 mask / markup 的作用对象,其余为参考图片。

Items1 <= items <= 16
mask?|
markup?|

Response Body

成功响应。

  1. response
created*integer

Unix 秒级时间戳。

data?array<>
background?string
Value in"opaque""transparent"
output_format?string
Value in"png""jpeg""webp""gif""svg"
quality?string
Value in"low""medium""high""xhigh""max"
size?string

实际输出尺寸 WIDTHxHEIGHT;GIF 表示每帧尺寸。

safety_identifier?|

生效的标识符;优先为请求中的非空 safety_identifier,否则为 user 回退值。

usage?

图像模型的实际 token 用量;SVG 作者用量单独位于 svg_usage,不合并进此对象。

svg_usage?

编写 SVG 的作者模型用量,与图像渲染 usage 分开统计。

curl -X POST 'https://goldflow.cc/v1/images/edits?async=true' \  -H 'Content-Type: application/json' \  -d '{  "model": "gpt-image-2.6-flare",  "prompt": "将标注圈出的花瓶改为蓝色,保留其他细节",  "images": [    {      "image_url": "https://example.com/source.webp"    }  ],  "markup": {    "image_url": "https://example.com/markup.png"  },  "complexity": "low",  "output_format": "png"}'
Example Response
{  "created": 0,  "data": [    {      "b64_json": "string"    }  ],  "background": "opaque",  "output_format": "png",  "quality": "low",  "size": "string",  "safety_identifier": "string",  "usage": {    "input_tokens": 0,    "input_tokens_details": {      "image_tokens": 0,      "text_tokens": 0    },    "output_tokens": 0,    "output_tokens_details": {      "image_tokens": 0,      "text_tokens": 0    },    "total_tokens": 0  },  "svg_usage": {    "model": "string",    "input_tokens": 0,    "output_tokens": 0,    "reasoning_tokens": 0,    "total_tokens": 0  }}