接口与鉴权

所有本站请求使用基础地址 https://top.qingyuntop.ai。请求头为 Authorization: Bearer YOUR_API_KEY，将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的一个空格。无需额外登录接口，也不需要 Vidu 厂商 Token。

用途方法与地址
查询任务GET https://top.qingyuntop.ai/v1/videos/{task_id}
下载视频GET https://top.qingyuntop.ai/v1/videos/{task_id}/content

task_id 是创建响应的 id，按原样保存和传入。示例中的 TASK_ID 必须替换成真实返回值，不能使用厂商回调中的私有任务编号。查询和下载需要有任务访问权限的青云 API Key。

创建响应与状态

以下是结构示意，实际 ID、时间和进度以返回值为准：

{
  "id": "TASK_ID",
  "object": "video",
  "model": "",
  "status": "queued",
  "progress": 0,
  "created_at": 1789776000
}
status含义下一步
queued已提交或排队等待后继续查询
in_progress生成中继续查询
completed任务成功请求下载接口
failed任务失败查看 error；修正原因后决定是否重新提交
unknown暂无可识别状态记录 ID 并稍后查询，不应当作成功

响应中的 model 可能为空字符串，业务系统请保存创建请求中的模型名。progress 是进度提示，不能单独用它判断成功；completed_at 可能由任务更新时间填充，存在此字段也不表示已完成。最终以 status 为准。

查询示例

点击标签切换 cURL、Python 或 Node.js。cURL 为 Bash 写法；Python 需安装 requests；Node.js 使用 18 或更新版本（含导入语句时保存为 .mjs）。图片示例使用 Vidu 官方示例素材，也可换成你自己的公开可访问图片 URL。

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

建议从每 5–10 秒查询一次开始，按业务需要设置等待上限；遇到限流使用退避。达到本机等待上限表示停止等待，不表示任务失败或自动取消；保留 ID 稍后继续查询。创建响应不确定时不要立即反复提交，以免产生重复任务和费用。

下载示例

确认 status=completed 后调用下方接口，将响应按二进制保存，不能调用 JSON 解析方法。

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

本接口只返回首条生成结果对应的视频，不保证提供完整的 creations 数组或封面。任务成功但没有可用的视频地址时，请保留任务 ID 和脱敏错误联系本站支持。

Vidu 官方生成文件 URL 有效期为 24 小时；本站内容接口依赖上游产物，并不承诺永久存储。请及时下载到自己的存储，不要把青云 API Key 附加到厂商 CDN 地址或网页播放地址中。

失败示例

{
  "id": "TASK_ID",
  "object": "video",
  "model": "",
  "status": "failed",
  "progress": 0,
  "created_at": 1789776000,
  "error": {
    "message": "ImageDownloadFailure",
    "code": "ImageDownloadFailure"
  }
}

不同失败阶段可能返回不同错误结构，详情见状态码、错误与回调。通过 Responses 创建的任务优先按 Responses 查询与下载处理其返回结构。