Skip to main content
POST
本页适用于 GPT Image 2.5。使用 gpt-image-2 请查看 GPT Image 2 API 通过 POST https://code.heihuzi.ai/v1/images/edits 上传参考图并描述修改要求。验证日期:2026-09-13。请使用具有图片权限的 API Key,并设置环境变量 HEIHUZI_API_KEY。本页 SDK 示例使用已验证的 OpenAI Python SDK 2.32.0

输入方式

Flare、Sunburst 的远程 URL 测试使用公开 PNG 图片;下方 Flare 完整示例另已验证本站的参考图 URL。JSON 参考图和遮罩都填写完整 Data URL。images[].file_idmask.file_id 均实测返回 400。 下载参考图 reference.png到运行目录后,可以直接运行下面的单图编辑示例。
单文件示例将响应保存为 edits-multipart.json;JSON 中的 data[].b64_json 是输出图片。

JSON 编辑并保存图片

公开 URL 参考图

此示例直接传入公开图片 URL,将蓝色杯子改为红色,响应保存到 edited-url.json

请求参数

string
default:"gpt-image-2.5-flare"
本页使用 gpt-image-2.5-flaregpt-image-2.5-sunburst。建议显式填写;省略模型的请求及实际调度记录已确认使用 Flare。
string
required
描述图片内容或编辑要求。缺少提示词的请求返回 400。
integer
default:"1"
返回图片张数。两个模型省略时均返回一张;Flare、Sunburst 已验证 12。客户端遍历实际返回的 data 数组。
string
Flare、Sunburst 已验证 1024x10241536x10241024x1536auto。省略尺寸的测试返回 1254x1254,因此需要固定尺寸时请显式填写。
string
Flare、Sunburst 已验证 lowmediumhighxhighmaxauto。质量测试使用一张 1024x1024 PNG。
string
Flare、Sunburst 已验证 transparent 搭配 PNG/WebP、opaque 搭配 JPEG、auto 搭配 WebP。透明输出文件已检查实际 alpha 通道,具体组合见下表。
string
Flare、Sunburst 已验证 pngjpegwebp,返回内容解码后与所请求的编码一致。
integer
JPEG 已验证 0100;WebP 已验证 50。PNG 示例省略此字段。
boolean
default:"false"
Flare、Sunburst 设置 true 后实际返回 SSE;省略时返回 JSON。见图片流式返回
integer
流式模式已验证 0123-14 返回 400。实际预览数可以少于请求值,最终图片以完成事件为准。此参数与最终图片张数 n 分开使用。
object[]
JSON 参考图数组;本页验证了一张和两张参考图。multipart 改用 imageimage[] 文件字段。缺少参考图返回 400。
object
JSON 遮罩对象;multipart 改用 mask 文件字段。

已验证的输出组合

编辑测试使用同一张蓝色杯子参考图,提示词要求改为红色杯子;透明组合额外要求透明背景。 以下每行分别经过 Flare 和 Sunburst 实际调用。基准为 n: 1size: "1024x1024"quality: "low"output_format: "png";每行仅替换列出的参数。表格说明这些已测组合。 透明输出的提示词也明确要求透明背景。跨行叠加参数会形成新的组合,应先在业务中验证再采用。

两张参考图

下载蓝色杯子 reference.png红色色板 palette.png到运行目录。重复上传两个 image[] 字段,提示词要求保留第一张图的杯形并采用第二张图的红色。完整示例已返回红色杯子,响应保存到 edited-multi.json

遮罩编辑

下载mask.png到运行目录。遮罩与参考图同为 1024×1024,右侧带透明区域。下面完整示例在右侧添加红苹果并保留蓝色杯子,响应保存到 edited-mask.json。Flare、Sunburst 的 JSON / multipart 遮罩测试也已返回对应内容,并经过目视检查。输出图片请另存。

Python 流式编辑

编辑接口使用 image_edit.partial_imageimage_edit.completed 事件。下面代码已真实读取预览和完成事件,并将最终红色杯子保存为 edited-final-1.png
partial_images: 1 不保证返回预览;代码以最终完成事件为成功依据。更多已测取值和事件记录见图片流式返回

真实响应节选

以下取自上方公开 URL 编辑示例的实际响应,仅省略图片 base64。图片从 data[].b64_json 解码;固定 PNG 输出可按前面的 Python 示例保存文件。