查询接口与鉴权

GET https://top.qingyuntop.ai/v1/responses/{response_id}

请求头：Authorization: Bearer YOUR_API_KEY。把 response_id 换成创建响应的 resp_… ID；下载使用 metadata.task_id，两者不可互换。

返回状态

状态处理
queued / in_progress继续等待，建议每 10 秒查询一次。
completed从 metadata.task_id 取得公共视频任务 ID 并下载。
failed检查 error，修正请求后再创建。
incomplete（SSE 观察结果）本次观察未完成，使用 Response ID 继续 GET。

完成结果的 output 中会有 message，content 的 output_text 含视频预览标签。它不是 MP4 字节；下载不需要解析 HTML。Responses usage 可能为空或是兼容用量，不作为视频账单依据。

{
  "id": "resp_doubao_example",
  "object": "response",
  "status": "completed",
  "metadata": {
    "task_id": "task_doubao_example",
    "vendor": "doubao"
  },
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "<video controls src=\"https://example.com/video-preview\"></video>"
        }
      ]
    }
  ]
}

后台查询与下载代码

在创建示例取得 ID 后执行。Python 需 requests；Node.js 使用 22+ .mjs。默认保存 MP4，选择 mov 时更改文件后缀。

curl --fail-with-body "https://top.qingyuntop.ai/v1/responses/resp_doubao_example" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos/task_doubao_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o doubao-video.mp4

同步模式

创建请求设置 background: false、stream: false，其他字段不变。请求等待模型结果，但不能保证整个生成过程在一次 HTTP 连接内完成。观察超时可能返回 queued，继续用 id 查询，不要再次提交同一个 POST。

SSE 流式模式

在创建请求设置 stream: true；HTTP 返回 Content-Type: text/event-stream。SSE 传输任务进度与完成文本，视频仍在任务完成后下载。下面显示原始事件，接入应用时根据 event 名与 data JSON 更新进度；多行 data 需按 SSE 规范拼接。

curl --fail-with-body -N --max-time 1800 "https://top.qingyuntop.ai/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2-5-260628","input":"猫走过雨后屋顶，镜头缓慢推进。","seconds":5,"metadata":{"resolution":"720p","ratio":"16:9"},"stream":true,"background":false}'

常见事件为 response.created、response.in_progress、response.output_item.added、response.content_part.added、response.output_text.delta、response.output_text.done、response.content_part.done、response.output_item.done、response.completed；错误或观察超时分别可能为 response.failed 或 response.incomplete。请按这些 SSE 事件名处理，不要使用 progress/output 作为事件名。收到 response.created 后保存 Response ID，连接断开仍可继续 GET 查询。

错误处理

情况处理
401 / 403检查青云 Key、访问权限和模型分组。
创建 400检查模型参数、角色、时长和清晰度；2.5 编辑必须 duration=-1、ratio=adaptive。
404核对 ID 类型、所属账号与完整路径；不要给任务列表旧接口补参数。
429 或查询 5xx延迟重试 GET，增加轮询间隔，不要重发 POST 创建。
InvalidParameter.TaskTypeConstraint / TaskTypeMismatch核对 2.5 的任务类型、素材和提示词是否一致。
素材无法读取使用直达文件的 HTTPS URL 或完整图片 data URL，确保无登录限制、未过期。
artifact_not_found 或下载失败确认任务成功且存在 content.video_url；上游链接过期时内容代理也无法恢复。

创建请求超时且没有 ID 时先检查任务日志。本文未约定幂等键行为，不应自动重复 POST。失败后修正参数再提交新任务。

官方说明视频 URL 通常有效 24 小时，2.5 视频下载有次数限制，成功后及时保存；这不是青云永久存储承诺。