查询视频生成任务

文档版本：v1.0.0 | 最后更新：2026-06-11
本平台已完整适配豆包 Seedance 系列官方视频生成接口，请求与响应均为透传，参数语义与官方一致。

根据任务 ID 查询视频生成任务的详细信息，包括任务状态、生成结果、用量统计等。

GET https://platform.shuyanai.com/seedance/api/v3/contents/generations/tasks/{id}

请求参数

路径参数

参数	类型	必填	说明
`id`	string	是	视频生成任务 ID。由创建视频生成任务接口返回。任务 ID 仅保存 7 天（从 created_at 时间戳开始计算），超时后将自动清除。

请求头

头部	必填	说明
`Authorization`	是	`Bearer {API_KEY}`

请求示例

响应参数

id string

视频生成任务 ID。

model string

调用的模型 ID。

content object

模型生成的输出内容。仅在任务成功（status=succeeded）后返回该字段；任务排队中 / 进行中 / 失败时不返回该字段（注意：不是空数组 []）。

字段	类型	说明
`content.video_url`	string	生成视频的 URL，格式为 mp4。有效期为 24 小时，请及时下载或转存。
`content.last_frame_url`	string	视频的尾帧图像 URL。有效期为 24 小时。仅在创建任务时设置 `return_last_frame=true` 且任务成功时返回。格式为 png，宽高像素值与生成的视频保持一致，无水印。

status string

任务当前状态：

状态	含义
`queued`	排队中
`running`	生成中
`succeeded`	生成成功
`failed`	生成失败
`cancelled`	已取消（取消状态 24h 自动删除）
`expired`	已过期（任务超时）

created_at integer

任务创建时间，Unix 时间戳（秒）。

updated_at integer

任务最近一次更新时间，Unix 时间戳（秒）。

service_tier string

任务使用的服务等级类型。

default：在线推理模式。

flex：离线推理模式。

duration integer

实际生成视频的时长，单位：秒。仅在任务成功后返回。当创建任务时 duration 设置为 -1（由模型自主选择时长）时，可通过此字段获取实际生成视频的时长。

seed integer

实际使用的种子值。当创建任务时 seed 设置为 -1（随机）时，可通过此字段获取实际使用的种子值。

error object

任务失败时的错误信息。

字段	类型	说明
`error.code`	string	错误码
`error.message`	string	错误详情描述

usage object

任务的用量统计信息。仅在任务成功后返回。

字段	类型	说明
`usage.completion_tokens`	integer	生成视频消耗的 token 数。Seedance 2.0 系列存在最低 token 消耗限制（即使生成较短视频，也会按最低值计费）。
`usage.total_tokens`	integer	总消耗 token 数。当前 `total_tokens = completion_tokens`（无 input tokens 概念）。
`usage.tool_usage`	object	工具调用用量（仅在使用 tools 参数时返回）
`usage.tool_usage.web_search`	integer	联网搜索实际调用次数

metadata object

任务的元数据信息。

字段	类型	说明
`metadata.draft`	boolean	是否为样片任务。`true` 为样片任务，`false` 为正式任务。

其他回显参数

任务成功后，响应中还会回显本次任务实际生效的参数（透传自上游），包括：

字段	类型	说明
`resolution`	string	实际生成视频的分辨率
`ratio`	string	实际生成视频的宽高比
`framespersecond`	integer	实际帧率（当前为 24）
`generate_audio`	boolean	是否生成有声视频
`draft`	boolean	是否为样片任务
`priority`	integer	任务执行优先级
`execution_expires_after`	integer	任务超时阈值（秒）

⚠️ 任务刚创建时的返回说明
创建任务后**极短时间内（约 10 秒内）**立即查询，可能仅返回 {"id": "cgt-..."}（只有 id，无 status 及其他字段）。这是任务尚未在上游完成初始化登记所致，属正常现象。
建议：创建任务后首次查询延迟 ≥10 秒，之后按 10 秒间隔轮询即可正常获取 status。此现象不影响视频生成本身。

响应示例

任务成功

{
  "id": "cgt-20250611100000-xxxxx",
  "model": "{MODEL_ID}",
  "content": {
    "video_url": "https://example.com/generated_video.mp4"
  },
  "status": "succeeded",
  "created_at": 1749619200,
  "updated_at": 1749619320,
  "service_tier": "default",
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "seed": 11,
  "generate_audio": false,
  "draft": false,
  "priority": 0,
  "execution_expires_after": 172800,
  "usage": {
    "completion_tokens": 12000,
    "total_tokens": 12000
  },
  "metadata": {
    "draft": false
  }
}

任务成功（含尾帧）

{
  "id": "cgt-20250611100000-xxxxx",
  "model": "{MODEL_ID}",
  "content": {
    "video_url": "https://example.com/generated_video.mp4",
    "last_frame_url": "https://example.com/last_frame.png"
  },
  "status": "succeeded",
  "created_at": 1749619200,
  "updated_at": 1749619320,
  "service_tier": "default",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 8,
  "framespersecond": 24,
  "seed": 42,
  "generate_audio": false,
  "draft": false,
  "priority": 0,
  "execution_expires_after": 172800,
  "usage": {
    "completion_tokens": 19200,
    "total_tokens": 19200
  },
  "metadata": {
    "draft": false
  }
}

任务进行中

{
  "id": "cgt-20250611100000-xxxxx",
  "model": "{MODEL_ID}",
  "status": "running",
  "created_at": 1749619200,
  "updated_at": 1749619260,
  "service_tier": "default",
  "metadata": {
    "draft": false
  }
}

任务刚创建（尚未初始化）

{
  "id": "cgt-20250611100000-xxxxx"
}

创建任务后约 10 秒内立即查询可能出现此返回，属正常现象，延迟后重试即可获取完整状态。

任务失败

{
  "id": "cgt-20250611100000-xxxxx",
  "model": "{MODEL_ID}",
  "status": "failed",
  "created_at": 1749619200,
  "updated_at": 1749619320,
  "service_tier": "default",
  "error": {
    "code": "ContentFilteredError",
    "message": "The content was filtered due to policy violations."
  },
  "metadata": {
    "draft": false
  }
}

轮询建议

建议轮询间隔不低于 10 秒。

轮询直至 status 为 succeeded、failed、cancelled 或 expired 时停止。

任务成功后，content.video_url 有效期为 24 小时，请及时下载或转存。

任务 ID 保留 7 天（从 created_at 开始计算），超时后自动清除，不可再查询。

02-查询视频生成任务

查询视频生成任务#

请求参数#

路径参数#

请求头#

请求示例#

响应参数#

响应示例#

任务成功#

任务成功（含尾帧）#

任务进行中#

任务刚创建（尚未初始化）#

任务失败#

轮询建议#