> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heihuzi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# GPT Image 2.5 图像生成
> 经过生产 API 验证的生成请求、参数组合和图片响应。
本页适用于 GPT Image 2.5。使用 `gpt-image-2` 请查看 [GPT Image 2 API](/cn/api-reference/images/gpt-image-2/generation)。
通过 `POST https://code.heihuzi.ai/v1/images/generations` 生成图片。验证日期：**2026-09-13**。请使用具有图片权限的 API Key；无图片权限的 Key 实测返回 403。
```bash theme={null}
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**。
## 请求参数
本页使用 `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`。建议显式填写；省略模型的请求及实际调度记录已确认使用 Flare。
描述要生成的图片内容。缺少提示词的请求返回 400。
返回图片张数。两个模型省略时均返回一张；Flare、Sunburst 已验证 `1`、`2`。客户端遍历实际返回的 `data` 数组。
Flare、Sunburst 已验证 `1024x1024`、`1536x1024`、`1024x1536`、`auto`。省略尺寸的测试返回 `1254x1254`，因此需要固定尺寸时请显式填写。
Flare、Sunburst 已验证 `low`、`medium`、`high`、`xhigh`、`max`、`auto`。质量测试使用一张 `1024x1024` PNG。
Flare、Sunburst 已验证 `transparent` 搭配 PNG/WebP、`opaque` 搭配 JPEG、`auto` 搭配 WebP。透明输出文件已检查实际 alpha 通道，具体组合见下表。
Flare、Sunburst 已验证 `png`、`jpeg`、`webp`，返回内容解码后与所请求的编码一致。
JPEG 已验证 `0`、`100`；WebP 已验证 `50`。PNG 示例省略此字段。
Flare、Sunburst 设置 `true` 后实际返回 SSE；省略时返回 JSON。见[图片流式返回](/cn/api-reference/images/gpt-image-2.5/streaming)。
流式模式已验证 `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 已省略。
```json theme={null}
{
"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` 中有可解码图片。[认证与错误](/cn/authentication)列出本次实际触发的错误；[图片常见问题](/cn/faqs/images)说明异步接口的当前状态。
## Python 生成并保存图片
这段完整代码已真实执行，返回并保存一张 1024×1024 PNG 到 `generated-1.png`。
```python theme={null}
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`。此示例已真实收到预览及完成事件，且两张图片均能解码。
```python theme={null}
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` 为成功依据，详细事件记录见[图片流式返回](/cn/api-reference/images/gpt-image-2.5/streaming)。