curl --fail-with-body --silent --show-error --max-time 600 \
--request POST \
--url https://code.heihuzi.ai/v1/images/generations \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5-flare",
"prompt": "A simple blue ceramic cup on a white background.",
"n": 1,
"size": "1024x1024",
"quality": "low",
"output_format": "png"
}' \
--output generation.json
{
"created": 1789276316,
"background": "opaque",
"data": [
{
"b64_json": "<此处省略真实图片的 base64>",
"generation_id": "4711ee57-f48f-4103-b973-cacda80439d7"
}
],
"output_format": "png",
"quality": "low",
"size": "1024x1024",
"usage": {
"input_tokens": 16,
"input_tokens_details": {
"image_tokens": 0,
"text_tokens": 16
},
"output_tokens": 196,
"output_tokens_details": {
"image_tokens": 196,
"text_tokens": 0
},
"total_tokens": 212
}
}
GPT Image 2.5
GPT Image 2.5 图像生成
经过生产 API 验证的生成请求、参数组合和图片响应。
POST
/
v1
/
images
/
generations
curl --fail-with-body --silent --show-error --max-time 600 \
--request POST \
--url https://code.heihuzi.ai/v1/images/generations \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5-flare",
"prompt": "A simple blue ceramic cup on a white background.",
"n": 1,
"size": "1024x1024",
"quality": "low",
"output_format": "png"
}' \
--output generation.json
{
"created": 1789276316,
"background": "opaque",
"data": [
{
"b64_json": "<此处省略真实图片的 base64>",
"generation_id": "4711ee57-f48f-4103-b973-cacda80439d7"
}
],
"output_format": "png",
"quality": "low",
"size": "1024x1024",
"usage": {
"input_tokens": 16,
"input_tokens_details": {
"image_tokens": 0,
"text_tokens": 16
},
"output_tokens": 196,
"output_tokens_details": {
"image_tokens": 196,
"text_tokens": 0
},
"total_tokens": 212
}
}
本页适用于 GPT Image 2.5。使用
请求会把完整响应保存到
透明输出的提示词也明确要求透明背景。跨行叠加参数会形成新的组合，应先在业务中验证再采用。
gpt-image-2 请查看 GPT Image 2 API。
通过 POST https://code.heihuzi.ai/v1/images/generations 生成图片。验证日期：2026-09-13。请使用具有图片权限的 API Key；无图片权限的 Key 实测返回 403。
curl --fail-with-body --silent --show-error --max-time 600 \
--request POST \
--url https://code.heihuzi.ai/v1/images/generations \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "gpt-image-2.5-flare",
"prompt": "A simple blue ceramic cup on a white background.",
"n": 1,
"size": "1024x1024",
"quality": "low",
"output_format": "png"
}' \
--output generation.json
generation.json。本页下方提供生成并保存 PNG、读取图片流式返回的完整 Python 代码。运行前设置 HEIHUZI_API_KEY；Python 示例使用已验证的 OpenAI Python SDK 2.32.0。
请求参数
string
default:"gpt-image-2.5-flare"
本页使用
gpt-image-2.5-flare 或 gpt-image-2.5-sunburst。建议显式填写；省略模型的请求及实际调度记录已确认使用 Flare。string
required
描述要生成的图片内容。缺少提示词的请求返回 400。
integer
default:"1"
返回图片张数。两个模型省略时均返回一张；Flare、Sunburst 已验证
1、2。客户端遍历实际返回的 data 数组。string
Flare、Sunburst 已验证
1024x1024、1536x1024、1024x1536、auto。省略尺寸的测试返回 1254x1254，因此需要固定尺寸时请显式填写。string
Flare、Sunburst 已验证
low、medium、high、xhigh、max、auto。质量测试使用一张 1024x1024 PNG。string
Flare、Sunburst 已验证
transparent 搭配 PNG/WebP、opaque 搭配 JPEG、auto 搭配 WebP。透明输出文件已检查实际 alpha 通道，具体组合见下表。string
Flare、Sunburst 已验证
png、jpeg、webp，返回内容解码后与所请求的编码一致。integer
JPEG 已验证
0、100；WebP 已验证 50。PNG 示例省略此字段。integer
流式模式已验证
0、1、2、3；-1、4 返回 400。实际预览数可以少于请求值，最终图片以完成事件为准。此参数与最终图片张数 n 分开使用。已验证的参数组合
以下每行分别经过 Flare 和 Sunburst 实际调用。基准为n: 1、size: "1024x1024"、quality: "low"、output_format: "png"；每行仅替换列出的参数。表格说明这些已测组合。
| 场景 | 在基准请求上替换的参数 | 实际结果 |
|---|---|---|
| 质量档位 | quality 分别为 medium、high、xhigh、max、auto | 均返回有效 PNG；非 auto 档位在响应中对应返回 |
| 横图 | size: "1536x1024" | 1536×1024 PNG |
| 竖图 | size: "1024x1536" | 1024×1536 PNG |
| 自动尺寸 | size: "auto" | 返回可解码图片，读取响应 size |
| 两张图片 | n: 2 | data 中两张有效图片 |
| 透明 PNG | background: "transparent" | 含透明像素的 PNG |
| 透明 WebP | background: "transparent"、output_format: "webp"、output_compression: 50 | 含透明像素的 WebP |
| JPEG | background: "opaque"、output_format: "jpeg"，output_compression 分别为 0、100 | 均为有效 JPEG |
| WebP | background: "auto"、output_format: "webp"、output_compression: 50 | 有效 WebP |
真实响应节选
下面保留一次真实响应的字段，图片 base64 已省略。{
"created": 1789276316,
"background": "opaque",
"data": [
{
"b64_json": "<此处省略真实图片的 base64>",
"generation_id": "4711ee57-f48f-4103-b973-cacda80439d7"
}
],
"output_format": "png",
"quality": "low",
"size": "1024x1024",
"usage": {
"input_tokens": 16,
"input_tokens_details": {
"image_tokens": 0,
"text_tokens": 16
},
"output_tokens": 196,
"output_tokens_details": {
"image_tokens": 196,
"text_tokens": 0
},
"total_tokens": 212
}
}
data[].b64_json 解码后是图片文件；output_format、size、quality、background 是本次返回的元信息。usage 为响应中的 token 计数。
成功处理应检查 HTTP 状态、JSON 是否含 error，并确认 data 中有可解码图片。认证与错误列出本次实际触发的错误；图片常见问题说明异步接口的当前状态。
Python 生成并保存图片
这段完整代码已真实执行，返回并保存一张 1024×1024 PNG 到generated-1.png。
import base64
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["HEIHUZI_API_KEY"],
base_url="https://code.heihuzi.ai/v1",
timeout=600.0,
max_retries=0,
)
result = client.images.generate(
model="gpt-image-2.5-flare",
prompt="A simple blue ceramic cup on a white background.",
n=1,
size="1024x1024",
quality="low",
output_format="png",
)
if not result.data:
raise RuntimeError("No image returned")
for index, item in enumerate(result.data, 1):
if not item.b64_json:
raise RuntimeError("Missing b64_json")
Path(f"generated-{index}.png").write_bytes(base64.b64decode(item.b64_json))
print("Saved", len(result.data), "image(s)")
Python 流式生图
生成接口的事件名为image_generation.partial_image 和 image_generation.completed。下面代码保存可能返回的预览图，并将最终图片另存为 final-1.png。此示例已真实收到预览及完成事件，且两张图片均能解码。
import base64
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["HEIHUZI_API_KEY"],
base_url="https://code.heihuzi.ai/v1",
timeout=600.0,
max_retries=0,
)
events = client.images.generate(
model="gpt-image-2.5-sunburst",
prompt="A simple blue ceramic cup on a white background.",
n=1,
size="1024x1024",
quality="low",
output_format="png",
stream=True,
partial_images=1,
)
completed = 0
for event in events:
print(event.type, flush=True)
if event.type == "image_generation.partial_image":
Path(f"preview-{event.partial_image_index}.png").write_bytes(
base64.b64decode(event.b64_json)
)
elif event.type == "image_generation.completed":
completed += 1
Path(f"final-{completed}.png").write_bytes(base64.b64decode(event.b64_json))
if completed != 1:
raise RuntimeError(f"Expected 1 final image, got {completed}")
partial_images: 1 不保证每次都返回预览。Flare、Sunburst 均出现过仅返回最终图片的实测结果；以 image_generation.completed 为成功依据，详细事件记录见图片流式返回。