跳转到内容
伯跃科技 · 文档

查询任务与获取视频

火山国内线已上线

这一页讲怎么用任务号轮询状态、读懂返回的字段，以及把生成好的视频取回来。

接口

Section titled “接口”
GET
https://api.boyueasi.com/api/v3/contents/generations/tasks/{task_id}

{task_id} 就是创建任务时返回的 id，形如 task_xxxxxxxx。请求头同样带 Authorization: Bearer <API 密钥>。带前缀的 /doubao/api/v3/contents/generations/tasks/{task_id} 与它等价。任务号不存在时返回 404，code 为 task_not_found。

状态机

Section titled “状态机”
status 含义 你要做什么
queued 已创建，排队中 继续轮询
running 生成中 继续轮询
succeeded 成功 读取 content.video_url，24 小时内下载
failed 失败 读取 error 了解原因；已预扣的费用自动全额退回
expired 任务超时 当作失败处理；已预扣的费用自动全额退回

火山方舟协议里还有一个 cancelled（已取消）。本站不提供取消功能，正常流程不会出现这个状态。

成功样例

Section titled “成功样例”

下面几份都是线上真实任务的返回，任务号和 URL 签名已省略。

刚创建时：

{
  "content": {},
  "created_at": 1793363023,
  "id": "task_xxxxxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued"
}

字段说明：

字段 说明
id、model、status 任务号、模型、当前状态
content.video_url 视频的下载直链，24 小时有效，见下文「视频链接」
content.last_frame_url 尾帧图的下载链接，只有创建时设置了 return_last_frame: true 才有，同样 24 小时有效
duration、ratio、resolution 实际生成视频的时长（秒）、画面比例、分辨率
usage.completion_tokens 本次实际用量，按它结算费用，对账用，见价格与计费
created_at、updated_at 创建与最近更新时间，Unix 时间戳（秒）

返回里可能还会出现上表没有列出的字段，不用处理，忽略即可。

失败样例

Section titled “失败样例”

任务失败时，status 是 failed，返回里带 error 对象，包含 error.code（错误码）和 error.message（失败原因）。以官方规格为准 结构如下，字段值只是占位：

{
  "id": "task_xxxxxxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "failed",
  "error": {
    "code": "<错误码>",
    "message": "<失败原因>"
  }
}

不管具体原因是什么，判断任务是否成功，只看 status，不要看 HTTP 状态码。失败的任务不收费，已预扣的费用会自动全额退回。常见失败原因和处理办法见错误与排错。

轮询建议

Section titled “轮询建议”
  • 查询间隔：建议每 10–15 秒查一次。网关目前没有设置查询限频，但请不要高频轮询。
  • 到终态就停：status 变成 succeeded、failed 或 expired 后，不用再查。
  • 不要重复创建：任务创建成功就已经入库，网关会在后台一直跟进到完成并结算，和你的程序是否在线无关，随时凭任务号查询即可。
  • 没拿到任务号时：如果创建请求超时或连接断开，没有收到返回的 id，先到控制台「常规 → 任务日志」确认任务有没有生成，再决定要不要重发，避免重复扣费。目前没有任务列表接口，任务号只能自己保存，或到控制台的「任务日志」里找。

视频链接

Section titled “视频链接”
  • content.video_url 是对象存储的签名直链，从视频生成完成时算起 24 小时有效，过期后无法下载，请拿到后尽快转存。
  • 直链下载最快，不需要带 API 密钥。
  • 备选方式：GET /v1/videos/{id}/content，{id} 填任务号，需要带 Authorization: Bearer <API 密钥>，支持 Range 请求，返回 video/mp4。它不支持 HEAD 请求（会返回 502），而且要经网关转发，速度比直链慢得多（我们实测 869KB 的文件下载了 36 秒），所以优先用直链。
  • 尾帧图 last_frame_url 的文件名以 _last-frame.png 结尾，但实际内容是 JPEG，保存或处理时请按文件内容识别格式，不要按后缀判断。

我们实测的成片规格：Seedance 2.0 / 480p / 4 秒是 864×496、24 帧、H.264 视频加 AAC 音频，约 0.87MB；Seedance 2.5 / 480p / 4 秒是 854×480、24 帧、H.264 加 AAC，约 4.3MB。

耗时参考

Section titled “耗时参考”

下面是线上实测的出片时间，仅供参考：

模型与规格 实测耗时
Seedance 2.0 / 480p / 4 秒 149 秒、272 秒（两次实测）
Seedance 2.5 / 480p / 4 秒 约 200 秒（其中一次 3 分 19 秒）

我们只实测过 480p、4 秒的规格，其他分辨率和时长暂时没有实测数据。排队情况不同，耗时会有波动，请按轮询到终态为准，不要用固定的等待时间。

© 伯跃科技