查询任务

  • 查询以 OpenAI 兼容格式提交的视频任务状态与结果
  • 状态流转：queued → in_progress → completed / failed
  • 完成后从 data.video_url 取直链，或用下载接口经网关取回
GET/v1/video/generations/{task_id}

认证

string必填

所有接口均使用 Bearer Token 进行认证。

Seedance 系列的接口需要在 ark 站 单独获取 Key，与 api 站的 Key 不通用。

请求时在请求头中添加：

Authorization: Bearer YOUR_ARK_KEY

路径参数

string必填

提交任务时返回的任务 ID。

状态流转

QUEUED -> IN_PROGRESS -> SUCCESS   成片可取
                     -> FAILURE   查看 fail_reason
  • QUEUED：已受理，排队中
  • IN_PROGRESS：生成中，data.progress 为百分比字符串，如 50%
  • SUCCESS：已完成，成片地址在 data.video_url
  • FAILURE：已失败，原因在 data.fail_reason

轮询节奏：每 5 秒一次，总超时约 10 分钟。多数 Seedance 任务在 1 到 3 分钟内完成。

响应

string

固定为 success。

string

通常为空字符串。

data 的元素字段 · 14 项
integer

任务在库内的自增 ID。

string

任务 ID，与请求路径里的值一致。

string

任务类型，如 text_to_video、image_to_video。

string

取值 QUEUED、IN_PROGRESS、SUCCESS、FAILURE。

string

失败原因，成功时为空字符串。

string

成片地址，成功后才有。

string

与 result_url 同值的成片地址，给按 OpenAI 视频字段名解析的客户端使用。成功后才有。

string

末帧图片地址。上游产出末帧时才有，例如豆包在提交时把 return_last_frame 设为 true。

string

进度百分比字符串，如 100%。

integer

提交时间，Unix 秒。

integer

开始时间，Unix 秒，未开始为 0。

integer

结束时间，Unix 秒，未结束为 0。

object

本次任务使用的模型信息，含 input、origin_model_name、upstream_model_name。

object

上游返回的原始任务快照。不同渠道结构不同，例如豆包是 { id, model, status, content: { video_url, last_frame_url }, usage }。

取回成片

SUCCESS 之后有两种取法：

  1. 直接用 data.video_url 里的直链
  2. 调 GET /v1/videos/{task_id}/content 经网关下载，需要鉴权，地址不外泄

错误码

HTTP含义
401Token 缺失或无效，type 为 authentication_error

更多状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

使用示例