GPT Image 流式生成与编辑 | 青云TOP API 文档

使用 SSE 在生成过程中接收中间预览，并在完成事件中保存最终图片；同一套事件处理也适用于图像编辑。

适用模型与事件含义

本页适用于 GPT Image 2.5 Sunburst、2.5 Flare、2、1.5 和 1 的 Images 请求。stream=true 改变响应方式，不会把图像请求变成可轮询的异步任务。

响应 Content-Type 为 text/event-stream。一个事件由空行分隔，可能跨越多个网络 chunk；不要对每个 chunk 直接执行 JSON 解析。预览图片不等于最终结果，也不是进度百分比。某些情况下只会收到最终事件，不能依赖一定有预览。

第一步：设置鉴权

请求头使用 Authorization: Bearer YOUR_API_KEY。将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的一个空格。基础地址为 https://top.qingyuntop.ai；使用 SDK 时，base_url 通常填写 https://top.qingyuntop.ai/v1。

第二步：开启流式请求

生成入口为 POST https://top.qingyuntop.ai/v1/images/generations，使用 JSON。编辑入口仍为 POST https://top.qingyuntop.ai/v1/images/edits，可使用 JSON 图片引用或文件表单。

请求参数

字段、类型与位置	填写规则与限制
`model`；string；JSON 顶层	必填；明确填写。本站调用请明确填写模型 ID；见模型表。不要省略，也不要填写不带 sunburst/flare 的 gpt-image-2.5。
`prompt`；string；JSON 顶层	必填；未指定默认值。必填，最多 32000 字符；描述主体、构图、文字与约束。编辑时说明修改目标和应保留内容。
`n`；integer；JSON 顶层	可选；默认 1。1–10 的整数；指输出图片数量，与输入素材数量不同。推荐先用 1。不要填写 0、小数或把通用上限当成模型上限。
`size`；string；JSON 顶层	可选；默认 auto。尺寸字符串使用半角 x；常用 1024x1024、1536x1024、1024x1536。2/2.5 的自定义尺寸规则见下文；示例均显式设置尺寸。
`quality`；string；JSON 顶层	可选；默认 auto。1/1.5/2 使用 auto、low、medium、high；2.5 的两个型号还支持 xhigh、max。不要使用 DALL·E 的 hd 或 standard。
`output_format`；string；JSON 顶层	可选；默认 png。png、jpeg、webp；控制图片文件编码。字段名不是 format；与 Base64 返回方式不是同一概念。
`stream`；boolean；JSON 顶层	可选；默认 false。false 返回完整 JSON；true 返回 SSE 事件。流式编辑仍使用相同的 edits 地址。
`partial_images`；integer；JSON 顶层	可选；默认 0。0–3 的整数，配合 stream=true；0 不请求中间预览，默认 0。最终结果可能提前完成，实际预览数可少于请求数。

下面示例使用 2.5 Flare、n=1、partial_images=2。预览索引从 0 开始，实际数量可能小于 2；只有完成事件中的图片用于最终交付。

三语言流式示例

cURL 使用 Bash 并支持 --fail-with-body，将完整 SSE 保存为 stream.sse；这是事件文本文件，不是图片。Python 需安装 requests；Node.js 需 20 或更新版本并保存为 .mjs。Python/Node.js 按 SSE 的行与空行边界解析、识别错误、保存最终图片，并检查最终图片是否齐全。

超时 600 秒是示例客户端设置；Python 的读取超时指没有收到数据的等待时间，Node.js/cURL 的总时限指本次请求持续时间，都不是服务端的生成时限。

curl --fail-with-body --connect-timeout 30 --max-time 600 --no-buffer "https://top.qingyuntop.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "一只坐在窗边读书的橘猫，温暖的水彩插画。",
  "n": 1,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "stream": true,
  "partial_images": 2
}' \
  --output stream.sse

事件和完成判断

类型	含义与处理
`image_generation.partial_image`	生成预览；读取 b64_json、partial_image_index，可临时展示，不标记最终完成
`image_edit.partial_image`	编辑预览，按相同方式处理
`image_generation.completed`	最终图片可用；解码 b64_json 并保存
`image_edit.completed`	编辑最终图片；处理方式与生成完成一致
`error`、`upstream_error` 或非空 error 字段	记录脱敏错误并结束本次消费；HTTP 200 也可能出现流内错误
`data: [DONE]` 或正常 EOF	流结束信号；仍需检查是否收到最终图片，不能单凭结束信号判定成功

完成事件通常带 created_at、output_format、size、quality、background 或 usage；兼容响应可能缺少部分辅助字段。程序应兼容两类完成事件，不依赖编辑请求一定使用 image_edit.completed。保存格式优先使用事件的 output_format，缺省时采用请求中明确设置的编码。

如何改为流式编辑

将图片上传或 JSON 编辑的请求体补充 stream=true、partial_images=2，保留原始图片和蒙版结构，再使用本页的事件消费逻辑。multipart 中这两个值是表单文本；JSON 中分别是布尔值和整数。

只把流式请求的 URL 改为 edits 而没有提供图片，会导致缺少输入错误。不要把图像 SSE 当作 Chat Completions 的 choices[].delta，也不要等待 Responses 的 response.completed 事件。

断线、超时与恢复

Images 流没有本目录可用的任务查询、断点续传或取消入口。断线、停止读取和本地超时不自动等于上游取消或生成失败；不要立即自动重发，否则可能重复生成并计费。

保留已收到的最终图片、请求时间、模型和脱敏错误；未收到最终结果时检查控制台记录，必要时联系本站支持确认，再决定是否重新提交。预览图不能替代丢失的最终结果。

官方参考：OpenAI Images 流事件定义。