豆包单图流式输出 | 青云TOP API 文档

开启 stream 后通过 SSE 接收图片完成事件，区分单张图片结果与整个请求的结束汇总，再保存图片。

功能与支持模型

5.0 Lite、4.5、4.0支持本页的单图流式调用。本页采用5.0 Lite、2K、PNG、URL输出。流式会推送生成完成事件，不保证持续进度百分比或中间预览图。Pro不适用本页示例。

第一步：设置鉴权

使用请求头 Authorization: Bearer YOUR_API_KEY。把 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后一个空格。

第二步：调用模型

向 https://top.qingyuntop.ai/v1/images/generations 发送 POST，保留 Content-Type: application/json，在JSON顶层设置 stream: true。正常流式响应为 text/event-stream。

请求参数

字段与类型	填写规则、默认值与限制
`model`；string	必填；JSON 顶层。使用本目录模型表的完整 ID，没有推荐默认型号。5.0 Lite 的本站 ID 不带 lite 后缀。
`prompt`；string	必填；JSON 顶层非空文本。说明主体、构图、风格和需要保留或修改的部分；多图可按数组顺序称图1、图2。支持中英文，建议中文不超过300字、英文不超过600词；这是写作建议，不是硬性长度上限。
`size`；string	可选；JSON 顶层。默认2048x2048。填模型允许的分辨率档位或宽x高字符串；两种方式选一种。像素值用 ASCII x，同时满足下表的总像素和宽高比限制。
`response_format`；string	可选；JSON 顶层。url 返回临时图片链接；b64_json 返回图片的纯 Base64 字符串。只改变返回方式，不改变图片编码。默认 url。
`output_format`；string	可选；JSON 顶层。仅本目录的5.0 Lite可设 png 或 jpeg。4.5、4.0输出JPEG，请省略此字段。请求PNG不等于支持透明背景。默认 jpeg。
`watermark`；boolean	可选；JSON 顶层布尔值。true 在右下角添加可见的“AI生成”水印，false 关闭该可见水印；不代表清除所有隐式标记。不要传字符串。默认 true。
`stream`；boolean	可选；JSON 顶层布尔值。false 等待完整JSON；true 消费SSE事件。本目录按单图请求使用，流式并非逐像素预览。默认 false。

单参考图或多参考图也可按对应教程加入 image，仍按一张输出处理。本页不配置组图参数。

代码示例

cURL示例使用Bash，需cURL 7.76+与jq；Python需3.10+并安装requests；Node.js需20+，保存为.mjs运行。600秒是示例的客户端超时设置，不是生成耗时承诺；Python的timeout分别控制连接和单次读取等待。代码会覆盖同名request.json或response.json，请按需另存。

cURL 使用 --no-buffer 将原始事件保存到 events.sse，需按下一节判断是否成功；HTTP 200与文件非空都不足以证明生成完成。Python与Node.js示例会解析事件，收到图片和完成事件后才写入可供下载的 response.json。cURL下载示例读取的是JSON，不能把 events.sse 重命名为 response.json。

set -euo pipefail
cat > request.json <<'JSON'
{
  "model": "doubao-seedream-5-0-260128",
  "prompt": "生成一张横向插画：海边灯塔与清晨薄雾，低饱和蓝色调，构图简洁，只生成一张图。",
  "size": "2K",
  "response_format": "url",
  "output_format": "png",
  "stream": true,
  "watermark": true
}
JSON
curl --no-buffer --fail-with-body --connect-timeout 30 --max-time 600 \
  "https://top.qingyuntop.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json --output events.sse
# 按事件表检查错误、图片及完成事件；events.sse不是response.json。
cat events.sse

事件与完成判断

事件type	字段与类型	处理方式
`image_generation.partial_succeeded`	`b64_json`（string）、`image_index`（integer）、`size`（string）、`url`（string）	单张图片成功。url与b64_json按返回方式选择读取，保存图片结果。
`image_generation.partial_failed`	`error`（object）、`code`（string）、`message`（string）、`image_index`（integer）	单张图片失败，code/message位于error中；本页单图请求按失败处理。
`image_generation.completed`	`usage`（object）、`generated_images`（integer）、`output_tokens`（integer）、`total_tokens`（integer）	整次请求结束，后三项位于usage中；通常没有图片字段。
`error`	`error`（object）、`code`（string）、`message`（string）	请求错误，code/message位于error中；停止消费并报告错误。

下列为合法的合成结构示意，URL仅为占位，不是可下载图片：

event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","image_index":0,"url":"https://example.invalid/generated.png","size":"2048x2048"}

event: image_generation.completed
data: {"type":"image_generation.completed","usage":{"generated_images":1,"output_tokens":16384,"total_tokens":16384}}

SSE事件由空行分隔，多个 data: 行需要合并后再解析JSON。网络chunk可能只包含半个UTF-8字符、半行或多个事件，不能对每个chunk直接调用JSON解析。示例也兼容图片字段直接出现在完成事件中的返回，但不会要求每个完成事件都有图片。

只收到 partial_succeeded 表示拿到了图片结果，仍应等待整请求汇总；只收到 completed 而没有任何图片则不能认定单图生成成功。[DONE] 可能出现，也可能没有；它本身不代替图片与完成事件。

保存与断线处理

Python和Node.js示例最终生成标准结构的 response.json，可继续运行图片保存代码。示例配置600秒客户端超时（Python为单次读取超时），不自动重试；请求超时、连接关闭或缺少完成事件时报告结果不确定。

本入口没有对应的任务查询或取消流程。断线不会保证取消生成；如需排查，请保留调用时间、模型、已收到的事件和脱敏错误联系本站支持，勿自动重发。

常见错误与参考

客户端收到JSON错误时应按HTTP状态和正文处理；SSE中的 error 或 partial_failed 也表示失败，不能只检查HTTP 200。更多排查见常见错误。参考：官方流式响应事件。