第一步：鉴权

请求头为 Authorization: Bearer YOUR_API_KEY 和 Content-Type: application/json。所有示例使用青云 API Key。

第二步：选择调用模式

场景参数返回与后续操作
服务端提交后交给任务队列处理background: true，stream: false返回 JSON 快照；保存 id，再调用 GET /v1/responses/{id}
简单脚本等待生成结果background: false，stream: false保持连接，通常完成后返回 JSON；若返回 queued，改为查询原 id
网页需要展示任务进度stream: true返回 SSE；保存 response.created 中的 response.id，按事件更新界面

background 与 stream 都省略时为同步模式。两者都为 true 时仍然是 SSE 连接。视频耗时较长，推荐后台创建示例；它更方便在进程重启后继续查询。

同步调用

在文生视频或图生视频示例中设置 background: false、stream: false，并把客户端读取超时调大，例如 660 秒。同步等待受服务端观察期限限制，网络也可能提前断开；请始终保存响应 ID，以便继续查询。

同步返回后仍要检查 status。completed 才下载，failed 查看错误，queued 或 in_progress 使用原 id 继续查询。服务端等待超时不等于生成已取消；不要重新 POST 来等待。

流式调用示例

POST https://top.qingyuntop.ai/v1/responses

stream: true 返回 Content-Type 为 text/event-stream。SSE 是文本事件，不能保存成 MP4。下列代码打印事件；它会提交真实生成任务。生成参数详见文生视频。

curl --no-buffer --fail-with-body --max-time 660 \
  https://top.qingyuntop.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "input": "An orange cat walks across a wet rooftop. Slow tracking shot, gentle rain sounds.",
    "seconds": 8,
    "metadata": {"resolution": "720p", "aspectRatio": "16:9"},
    "stream": true,
    "background": false
  }'

SSE 事件说明

每个 data 事件提供 JSON，包含 type 和递增的 sequence_number；心跳为注释行。上面的示例按行读取 data，不依赖网络分块边界。

事件处理方式
response.created从 response.id 保存响应 ID；metadata.task_id 为视频任务 ID
response.in_progress读取 response.status 和 response.metadata 中的进度信息；进度不是精确剩余时间
response.output_item.added、response.content_part.added开始结果消息和内容项
response.output_text.deltadelta 是结果文本片段，包含视频播放器标记；不是视频二进制
response.output_text.donetext 是该内容项的完整结果文本
response.content_part.done、response.output_item.done该内容项、消息结束
response.completed完成快照；按 metadata.task_id 下载视频
response.failed检查 response.error 和 metadata.task_status；任务或结果观察可能失败
response.incomplete本次流式观察未完成，使用原 response.id 继续 GET 查询

成功时 output 中的 output_text.text 包含 <video controls src="…"></video>。不要把同一段 delta 与 done 文本重复拼接。协议不会逐帧传回视频，下载方法见查询结果与下载视频。

断线和超时

SSE 断开不取消已经保存的任务。拿到 response.id 后，改用普通 GET 查询当前结果；此入口不提供 SSE 断点续传。未拿到 ID 时先查看控制台任务日志。同步观察超时可能返回 queued，流式观察超时返回 response.incomplete，两者都应继续查询原任务。HTTP 429 遵循 Retry-After，减少并发连接和轮询频率。