功能介绍

创建任务后，通过本站任务 ID 查询进度，成功后下载 MP4。查询和下载使用创建任务所属账户的青云TOP API Key，推荐继续使用创建时的 Key。

鉴权与操作步骤

所有请求发送到 https://top.qingyuntop.ai。在请求头填写 Authorization: Bearer YOUR_API_KEY，将 YOUR_API_KEY 替换为青云TOP API 控制台创建的 API Key；Bearer 与密钥之间保留一个空格。

  1. 使用创建响应中已保存的标识，携带鉴权请求头查询任务。
  2. 按状态继续等待或处理错误；成功且产物就绪后下载。无需再次创建任务。

GET 查询与下载不需要请求体。示例中的占位密钥需替换为你的 API Key。实际业务请在服务端保存密钥，不要放进公开网页。

查询接口

GET /v1/videos/{task_id}，无请求体。把示例中的 YOUR_TASK_ID 替换为创建响应的 id。

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

响应包含 id、object=video、status、progress，其他字段以实际返回为准。示意响应：

{"id":"YOUR_TASK_ID","object":"video","status":"queued","progress":0}
status含义与下一步
queued已排队，继续查询
in_progress正在生成，继续查询
completed生成成功，可以下载
failed任务失败，读取 error（若存在），检查参数或联系支持
unknown当前状态尚未识别，稍后重查，持续出现时提交任务 ID 排查

建议每 5–10 秒查询一次，遇到 429 按 Retry-After 或指数退避。设置业务等待期限，例如 20 分钟；到期保存 ID 稍后继续查询，不要自动重新创建任务。部分失败响应不带完整 error；不要因此当作成功。completed_at 或 progress 不能代替 status 判断。

下载接口

GET /v1/videos/{task_id}/content，请求头仍需 Bearer 鉴权，无请求体。只有任务成功、产物就绪后再调用。响应是视频字节，不要按 JSON 解析。

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos/YOUR_TASK_ID/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.mp4

下载成功后保存在 result.mp4。网络中断时可重试查询或下载，不要为获取文件而重建任务。产物链接可能过期，应及时保存；文档不承诺永久存储。

常见问题

401 检查 API Key 和 Bearer 空格；404 检查是否使用本站返回的 ID、是否属于当前账户、是否用了正确接口；下载过早可能返回“任务未完成”或“产物不存在”。成功状态与产物短暂不同步时，可稍后再次查询。