curl --fail-with-body --silent --show-error --max-time 600 \
--request POST \
--url https://code.heihuzi.ai/v1/images/edits \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--form 'model=gpt-image-2.6-sunburst' \
--form 'prompt=Change the blue cup to a bright red cup. Keep the cup shape and the white background.' \
--form 'image=@reference.png' \
--form 'n=1' \
--form 'size=1024x1024' \
--form 'quality=low' \
--form 'output_format=png' \
--output edits-multipart.json
{
"created": 1794058909,
"background": "opaque",
"data": [
{
"b64_json": "<此处省略真实图片的 base64>",
"generation_id": "e8ea7f47-4b57-4655-a6fe-c5e374a2bae5"
}
],
"output_format": "png",
"quality": "low",
"safety_identifier": null,
"size": "1024x1024",
"usage": {
"input_tokens": 1059,
"input_tokens_details": {
"image_tokens": 1024,
"text_tokens": 35
},
"output_tokens": 824,
"output_tokens_details": {
"image_tokens": 824,
"text_tokens": 0
},
"total_tokens": 1883
}
}
GPT Image 2.6
GPT Image 2.6 图像编辑
上传参考图生成新图片或 GIF 动图的完整实测示例。
POST
/
v1
/
images
/
edits
curl --fail-with-body --silent --show-error --max-time 600 \
--request POST \
--url https://code.heihuzi.ai/v1/images/edits \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--form 'model=gpt-image-2.6-sunburst' \
--form 'prompt=Change the blue cup to a bright red cup. Keep the cup shape and the white background.' \
--form 'image=@reference.png' \
--form 'n=1' \
--form 'size=1024x1024' \
--form 'quality=low' \
--form 'output_format=png' \
--output edits-multipart.json
{
"created": 1794058909,
"background": "opaque",
"data": [
{
"b64_json": "<此处省略真实图片的 base64>",
"generation_id": "e8ea7f47-4b57-4655-a6fe-c5e374a2bae5"
}
],
"output_format": "png",
"quality": "low",
"safety_identifier": null,
"size": "1024x1024",
"usage": {
"input_tokens": 1059,
"input_tokens_details": {
"image_tokens": 1024,
"text_tokens": 35
},
"output_tokens": 824,
"output_tokens_details": {
"image_tokens": 824,
"text_tokens": 0
},
"total_tokens": 1883
}
}
本页适用于 GPT Image 2.6。使用 2.5 请查看 GPT Image 2.5 API。
通过
下载参考图 reference.png到运行目录后,可以直接运行下面的示例。
响应保存为
跨行叠加参数会形成新的组合,请先在自己的业务里验证再使用。参数不合法时返回的 400 结构见图像生成的错误返回。
参考图会计入输入用量:这张 1024×1024 参考图计 1024 个图片输入用量。
POST https://code.heihuzi.ai/v1/images/edits 上传参考图并描述修改要求。验证日期:2026-11-07。请使用具有 GPT Image 2.6 权限的 API Key,并设置环境变量 HEIHUZI_API_KEY。
输入方式
| 输入方式 | 本次验证的字段 | 模型 |
|---|---|---|
| 文件上传 | multipart 文件字段 image;多张时重复上传 image[] | Flare、Sunburst |
| JSON Data URL | images: [{"image_url": "data:image/png;base64,..."}] | Flare、Sunburst |
| JSON 图片地址 | images: [{"image_url": "https://..."}] | Sunburst |
curl --fail-with-body --silent --show-error --max-time 600 \
--request POST \
--url https://code.heihuzi.ai/v1/images/edits \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--form 'model=gpt-image-2.6-sunburst' \
--form 'prompt=Change the blue cup to a bright red cup. Keep the cup shape and the white background.' \
--form 'image=@reference.png' \
--form 'n=1' \
--form 'size=1024x1024' \
--form 'quality=low' \
--form 'output_format=png' \
--output edits-multipart.json
edits-multipart.json,其中 data[].b64_json 是输出图片。
请求参数
参数名、取值和返回结构与 OpenAI 官方POST /v1/images/edits 一致。下面只列编辑接口实际调用过的取值,具体组合见已验证的参数组合。
填写
gpt-image-2.6-flare 或 gpt-image-2.6-sunburst。省略时本站使用 gpt-image-2.5-flare,和官方默认的 gpt-image-2.5-sunburst 不同,要用 2.6 请明确填写。已验证
png、jpeg、webp、gif。GIF 两款型号、multipart 和 JSON 两种写法都验证过,见下方参考图生成 GIF。已验证
1024x1024、1536x1024、1024x1536、2048x2048、2880x2880、auto(本次返回 1374x1145)。GIF 不填和填 512x512 都输出 512×512,填 1024x1024 返回 400。设置
true 后返回 SSE。Flare、Sunburst,multipart 和 JSON 请求都验证过。完成事件是 image_edit.completed;填了 partial_images 时,之前可能先收到 image_edit.partial_image 预览事件。请以完成事件作为成功依据。已验证的参数组合
以下每行都在正式环境实际调用,返回 200 并核对了图片文件。| 模型 | 写法 | 尺寸 | 质量 | 格式 | 其他 | 实际结果 |
|---|---|---|---|---|---|---|
| Sunburst | multipart image | 1024x1024 | low | png | 1024×1024 PNG,杯子变红 | |
| Flare | JSON Data URL | 1024x1024 | low | png | 1024×1024 PNG,杯子变红 | |
| Flare | multipart 两个 image[] | 1536x1024 | medium | jpeg | n: 2、output_compression: 50 | 两张 1536×1024 JPEG,第一张图的杯形配第二张图的红色 |
| Sunburst | JSON https 图片地址 | 2048x2048 | high | webp | stream: true、partial_images: 2 | 2 张 PNG 预览和 2048×2048 WebP 完成图 |
| Sunburst | multipart image | 2880x2880 | low | png | stream: true | 2880×2880 PNG 完成图 |
| Flare | multipart image | 1024x1024 | low | png | stream: true、partial_images: 1 | 1024×1024 PNG 完成图,没有预览 |
| Flare | JSON Data URL | auto | auto | png | background: "transparent"、moderation: "low"、safety_identifier、user | 1374×1145 透明背景 PNG,质量 medium |
| Flare | JSON Data URL | 1024x1536 | max | png | 1024×1536 PNG | |
| Sunburst | JSON Data URL | 1024x1024 | xhigh | png | complexity: "low" | 1024×1024 PNG |
| Flare | JSON Data URL | 1024x1024 | low | png | complexity 分别为 medium、high | 均为 1024×1024 PNG |
| Flare | JSON Data URL | 1024x1024 | low | png | n: 10 | 十张 1024×1024 PNG |
| Flare | JSON Data URL | 省略 | low | gif | frame_count: 9、frame_duration_ms: 200 | 512×512 GIF,9 帧,每帧 200 毫秒 |
| Sunburst | multipart image | 省略 | low | gif | frame_count: 4、frame_duration_ms: 100 | 512×512 GIF,4 帧,每帧 100 毫秒 |
| Flare | JSON Data URL | 512x512 | low | gif | frame_count: 12、frame_duration_ms: 500、moderation: "auto" | 512×512 GIF,12 帧,每帧 500 毫秒 |
| Sunburst | JSON Data URL | 省略 | low | gif | frame_count: 16、frame_duration_ms: 2000 | 512×512 GIF,16 帧,每帧 2000 毫秒 |
| Flare | JSON Data URL | 省略 | low | gif | frame_count: 2、frame_duration_ms: 20 | 512×512 GIF,2 帧,每帧 20 毫秒 |
| Flare | multipart image | 省略 | low | gif | 不填帧数和帧时长 | 512×512 GIF,9 帧,每帧 200 毫秒 |
JSON 编辑并保存图片
这段完整代码已真实执行,把蓝色杯子改成红色并保存为edited-1.png。
import base64
import os
from pathlib import Path
import requests
encoded = base64.b64encode(Path("reference.png").read_bytes()).decode("ascii")
response = requests.post(
"https://code.heihuzi.ai/v1/images/edits",
headers={"Authorization": f"Bearer {os.environ['HEIHUZI_API_KEY']}"},
json={
"model": "gpt-image-2.6-flare",
"prompt": "Change the blue cup to a bright red cup. Keep the cup shape and the white background.",
"images": [{"image_url": f"data:image/png;base64,{encoded}"}],
"n": 1,
"size": "1024x1024",
"quality": "low",
"output_format": "png",
},
timeout=600,
)
response.raise_for_status()
data = response.json()["data"]
for index, item in enumerate(data, 1):
Path(f"edited-{index}.png").write_bytes(base64.b64decode(item["b64_json"]))
print("Saved", len(data), "image(s)")
参考图生成 GIF
这段完整代码已真实执行,让参考图里的杯子上下跳动,保存为 512×512、9 帧的cup-bounce.gif。
import base64
import os
from pathlib import Path
import requests
encoded = base64.b64encode(Path("reference.png").read_bytes()).decode("ascii")
response = requests.post(
"https://code.heihuzi.ai/v1/images/edits",
headers={"Authorization": f"Bearer {os.environ['HEIHUZI_API_KEY']}"},
json={
"model": "gpt-image-2.6-flare",
"prompt": "Make the blue cup gently bounce up and down.",
"images": [{"image_url": f"data:image/png;base64,{encoded}"}],
"quality": "low",
"output_format": "gif",
"frame_count": 9,
"frame_duration_ms": 200,
},
timeout=600,
)
response.raise_for_status()
item = response.json()["data"][0]
Path("cup-bounce.gif").write_bytes(base64.b64decode(item["b64_json"]))
print("Saved cup-bounce.gif")
真实响应节选
下面是页首示例的一次真实响应,图片 base64 已省略。{
"created": 1794058909,
"background": "opaque",
"data": [
{
"b64_json": "<此处省略真实图片的 base64>",
"generation_id": "e8ea7f47-4b57-4655-a6fe-c5e374a2bae5"
}
],
"output_format": "png",
"quality": "low",
"safety_identifier": null,
"size": "1024x1024",
"usage": {
"input_tokens": 1059,
"input_tokens_details": {
"image_tokens": 1024,
"text_tokens": 35
},
"output_tokens": 824,
"output_tokens_details": {
"image_tokens": 824,
"text_tokens": 0
},
"total_tokens": 1883
}
}