查询与下载接口

GET https://top.qingyuntop.ai/doubao/api/v3/contents/generations/tasks/{task_id}

无需请求体。下载视频还可使用 GET https://top.qingyuntop.ai/v1/videos/{task_id}/content。

鉴权与任务 ID

每次查询与下载携带 Authorization: Bearer YOUR_API_KEY。用创建响应返回的原始 ID 替换示例；不要使用控制台登录令牌或供应商任务 ID。

状态和结果

状态含义
queued / pending已接收或排队。
running / processing生成中。
succeeded成功；读取 content.video_url。
failed / expired / cancelled失败、过期或取消，停止轮询。

查询结果可能出现 expired、cancelled 等终态，请一并处理并停止轮询，不要只等待 succeeded。部分响应仅提供 queued、running、succeeded、failed 四种状态。

结构示例；URL、任务 ID、用量均为示意：

{
  "id": "task_doubao_example",
  "status": "succeeded",
  "model": "doubao-seedance-2-5-260628",
  "content": {
    "video_url": "https://example.com/result.mp4",
    "last_frame_url": "https://example.com/last-frame.png"
  },
  "duration": 5,
  "resolution": "720p",
  "usage": {
    "completion_tokens": 108000,
    "total_tokens": 108000
  }
}
字段说明
id青云公共 ID；保留创建返回值。
content.video_url成功视频的临时地址；可直取，直取第三方存储时不要携带青云 Key。
content.last_frame_url创建时 return_last_frame=true 才可能返回，图片通常为 PNG。
error.code / error.message失败原因；创建 HTTP 成功后也可能异步报错。
usage.completion_tokens / total_tokens豆包返回的用量，不是金额；青云费用查看控制台。
duration / frames实际输出时长或帧数；duration 可能是实际帧数换算后向下取整的秒数。
draft / draft_task_id1.5 Pro 样片相关信息，其他 ID 字段不应假定都是青云公共 ID。

轮询并下载

下列代码使用青云 content 代理下载视频，无需解析临时存储地址。默认保存 MP4，创建时指定 mov 则更改文件名。Python 安装 requests，Node.js 使用 22+ .mjs。

curl --fail-with-body "https://top.qingyuntop.ai/doubao/api/v3/contents/generations/tasks/task_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

任务列表与保存期限

本目录接口不提供任务列表、批量搜索、取消或删除路由。业务程序应保存每次创建的 ID；多任务查询时逐个 GET，并控制并发。官方查询保留期为近 7 天、视频 URL 通常有效 24 小时，2.5 下载上限为 100 次。请及时下载，青云代理不会延长上游链接有效期。

用量与费用

视频用量受时长、分辨率及参考视频等因素影响。预估用量不等于最终账单，返回的 Token 数也不是金额。实际费用以青云任务日志和账号账单为准。

错误处理

情况处理
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 视频下载有次数限制，成功后及时保存；这不是青云永久存储承诺。