Skip to main content
GET
国内用户请注意: 中国大陆用户请使用 https://toapis.cn 作为接口地址(Base URL)。文档示例中的 https://toapis.com 请替换为 https://toapis.cn。
  • 查询异步视频生成任务的执行状态和结果
  • 实时状态更新和进度跟踪
  • 任务完成时获取生成的视频
  • 支持多语言返回(zh/en/ko/ja)
所有视频生成任务都是异步执行的。提交任务后,您需要通过查询接口获取任务状态和结果。
Seedance 视频任务需要素材审核时也通过本接口查询. queued 可能包含素材准备和审核等待, 返回任务不表示视频已经开始生成. 默认每轮准备期限为 20 分钟, 后续视频生成另计; 失败原因查看 error.message.
普通图片和视频任务也可通过 GET /v1/tasks/{task_id} 查询, usage 和 billing 采用相同口径. 本页描述的是页首生成任务查询路径的响应. 以下样例用于展示字段, 不代表模型的当前价格或固定计费方式. 实际字段和金额以本次任务返回为准.

Seedance 原始地址与备用地址

启用原始地址交付的 Seedance 任务, result.data[].url 保留上游原始视频 URL. 客户端应优先使用 url, 只有该地址无法访问时才切换到同一结果项的 fallback_url. 平台不会根据客户端所在地区自动切换地址. 备用字段均为可选: 只有副本准备成功时才返回. 未启用原始地址交付, 备用副本不可用或历史任务没有副本时, 字段可能缺省; 缺省不表示生成失败. 尾帧同样优先使用 last_frame_url, 不可访问时再使用 fallback_last_frame_url. 备用地址不延长原始 URL 的有效期, 需要长期保存时请及时下载.

创建任务时传入业务 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 时间戳. 当前用于 Seedance Global; generation.updated_at 是上游更新时间.
integer
任务创建时间(Unix 时间戳)
integer
任务结束时间, Unix 时间戳. 本页查询路径在任务成功或失败且已保存结束时间时返回.
integer
任务完成时间(Unix 时间戳,仅完成时返回)
integer
视频 URL 过期时间(Unix 时间戳,仅完成时返回)
object
任务结果(仅成功时返回)
object
可选的 Seedance 生成元数据. 仅返回已保存且可公开的字段, 不补默认值. 这些参数描述生成任务, 不替代顶层 usage 的计费量.generation.usage 是保留兼容的旧字段, 可包含 completion_tokens 和 total_tokens. 它可能缺失或与最终计费量不同, 不与顶层 usage 相加; 读取计费量使用顶层 usage.
object
可选的计费量, 视频 token 明细和工具次数. 各字段的单位和省略规则见任务用量字段.charge_type 到 input_images 是计费量, 只与 billing.status=settled 同时返回. 固定价视频按提交时确认的数量返回, 按实际时长或 token 结算的视频按最终结算数量返回. 未返回的字段直接省略, 不补零.
object
可选的平台计费状态和已确认费用. 计费状态独立于任务生成状态, completed 不保证已经结算. 缺少该对象不代表任务免费. 详见价格与实际费用.任务 Webhook 的 data.billing 使用相同的确认条件和取值.
object
错误信息(仅失败时返回)通常错误码和消息为字符串. Seedance Global 的 error.code 和 error.message 保留上游原始 JSON 值, 包括数字或 null; 上游缺失时不补平台默认值.

任务状态说明

轮询策略建议

Python 轮询示例

视频资源有效期

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

错误码与失败原因

请求错误和任务执行失败的区别, 具体错误标识与处理建议, 见错误码速查. 查询成功仍需检查任务状态, 不要把 HTTP 状态码当作业务错误码.

性能建议

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