Skip to main content
GET
  • 查询异步视频生成任务的执行状态和结果
  • 实时状态更新和进度跟踪
  • 任务完成时获取生成的视频
  • 支持多语言返回(zh/en/ko/ja)
所有视频生成任务都是异步执行的。提交任务后,您需要通过查询接口获取任务状态和结果。

创建任务时传入业务 ID

创建视频任务时,可以在请求体顶层传入 client_business_id。该字段用于保存您系统内的订单号、流水号或业务任务 ID,方便后续按业务 ID 查询生成结果。
也兼容放在 metadata.client_business_id 中,但推荐使用顶层字段。

Authorizations

string
必填
所有接口均需要使用 Bearer Token 进行认证获取 API Key:访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加:

Path Parameters

string
必填
视频生成 API 返回的任务 ID。也可以传创建任务时提交的 client_business_id,用于按客户侧业务 ID 查询任务状态和结果。
如果创建视频任务时传入 client_business_id,可直接使用同一个状态查询接口: GET /v1/videos/generations/{client_business_id}。业务 ID 会限定在当前 API Key 所属用户下查询。

Response

string
任务唯一标识符
string
客户侧业务 ID。仅当创建任务时传入 client_business_id 时返回。
string
对象类型,固定为 generation.task
string
使用的视频生成模型
string
任务状态
  • queued - 排队等待处理
  • in_progress - 处理中
  • completed - 成功完成
  • failed - 失败
integer
任务进度百分比(0-100)
integer
任务创建时间(Unix 时间戳)
integer
任务完成时间(Unix 时间戳,仅完成时返回)
integer
视频 URL 过期时间(Unix 时间戳,仅完成时返回)
object
任务结果(仅成功时返回)
object
模型工具用量。Seedance 2 启用 tools: [{ "type": "web_search" }] 时,usage.tool_usage.web_search 表示实际联网搜索次数;0 表示未搜索。
object
错误信息(仅失败时返回)

任务状态说明

轮询策略建议

Python 轮询示例

视频资源有效期

生成的视频 URL 有效期为 24 小时
  • 请在有效期内下载保存视频
  • expires_at 字段标识视频过期时间(Unix 时间戳)
  • 视频过期后无法访问,如需重新获取,需要重新提交生成任务
  • 缩略图与视频同步过期

常见错误

性能建议

视频生成耗时较长,建议:
  1. 使用 ToAPIs 统一任务 Webhook:以 Webhook 为主,轮询为兜底
  2. 合理设置轮询间隔:至少5~10秒并加入随机抖动;遇到429读取 Retry-After 后指数退避
  3. 设置超时时间:长视频生成可能需要5-10分钟,请设置合理的超时
  4. 及时下载保存:视频24小时后过期,请务必及时保存到自己的存储
查询限流和响应头见 异步任务速率限制。批量查询最多 100 个任务 ID。