> ## 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 流式返回

> 生成和编辑均经过真实 SSE 调用、预览与最终图片检查。

Flare、Sunburst 的生成和编辑接口均已验证 `stream: true`，实际响应为 `text/event-stream`。**流式完成与预览数量是两件事：收到可解码的完成图片，才能确认本次生成或编辑完成。**

验证日期：**2026-09-10**。测试参数为 `n: 1`、`size: "1024x1024"`、`quality: "low"`、`output_format: "png"`。

## 真实观测

下表列出 `partial_images: 1` 的四次调用；时间从发送请求开始计算，供理解事件先后顺序。

| 请求 | 模型       | 预览                                        | 完成                                    |
| -- | -------- | ----------------------------------------- | ------------------------------------- |
| 生成 | Flare    | 该次未返回预览                                   | 11.53 秒，`image_generation.completed`  |
| 生成 | Sunburst | 11.457 秒，`image_generation.partial_image` | 12.885 秒，`image_generation.completed` |
| 编辑 | Flare    | 该次未返回预览                                   | 12.418 秒，`image_edit.completed`       |
| 编辑 | Sunburst | 13.126 秒，`image_edit.partial_image`       | 14.844 秒，`image_edit.completed`       |

进一步测试 `partial_images: 2` 时，Flare 生成返回一张预览，Sunburst 生成只返回完成图片。因此，客户端需要处理**零张或少于请求值的预览**。上表是实测耗时记录，不是响应时间承诺。

`partial_images` 的 `0`、`1`、`2`、`3` 已分别验证；`0` 的调用只收到完成图片，`-1` 和 `4` 返回 400。最终张数由 `n` 指定，本页流式示例使用 `n: 1`。

## cURL 保存原始事件流

```bash theme={null}
curl --fail-with-body --silent --show-error --max-time 600 --no-buffer \
  --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-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
}' \
  --output stream.sse
```

完整 SSE 数据保存到 `stream.sse`，不能把整个文件当作一个 JSON 文档读取。

## Python SDK 保存预览和最终图片

以下完整代码已用 `openai==2.32.0` 实际运行，并检查生成的 PNG 文件。预览和完成事件的 `b64_json` 分别保存。

```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}")
```

## 编辑流式

在[JSON 编辑请求](/cn/api-reference/images/gpt-image-2.5/edits)中加入 `stream: true` 和 `partial_images: 1`，保留参考图数组。Flare、Sunburst 的这组请求均已验证。

编辑使用 `image_edit.partial_image` / `image_edit.completed`，生成使用 `image_generation.partial_image` / `image_generation.completed`。原始 SSE 以空行分隔事件，`data:` 为事件 JSON；接收端应持续读取到流结束并保存最终图片。未收到完成图片时，应记录响应并排查。