查询任务
GET /api/v3/contents/generations/tasks/{task_id}
请求参数
| 参数位置 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| 路径参数 | task_id | string | 是 | 创建任务响应中的任务 ID。当前创建响应的 task_id 与 id 值相同。 |
| 请求头 | Authorization | string | 是 | Bearer YOUR_API_KEY。 |
| 请求头 | Content-Type | string | 否 | 建议设置为 application/json;GET 请求不需要请求体。 |
curl -X GET /api/v3/contents/generations/tasks/task_xxx \
-H "Authorization: Bearer YOUR_API_KEY"成功响应
{
"id": "260e3207-aefd-4ca8-8f35-537a5990d172",
"model": "doubao-seedance-2-0-260128",
"status": "succeeded",
"created_at": 1790754352,
"updated_at": 1790754482,
"content": {
"video_url": "https://media.example.com/seedance/260e3207-aefd-4ca8-8f35-537a5990d172/3/video_url-84990293807539211ad19f60.mp4?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYmNjZDFkMmQ5ZWU0NDZjODlkOWJjMzZmMThiNjE1OWU%2F20260930%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260930T074817Z&X-Tos-Expires=86400&X-Tos-SignedHeaders=host&X-Tos-Signature=338b044e8c6e60e0fa3f68655c78bd7bc228569deb8cc50bc02105b9d472f048"
},
"usage": {
"completion_tokens": 40594,
"total_tokens": 40594
},
"seed": 68888,
"resolution": "480p",
"ratio": "16:9",
"duration": 4,
"framespersecond": 24,
"generate_audio": true,
"draft": false,
"service_tier": "default",
"execution_expires_after": 172800
}任务状态通常为 queued、running、succeeded 或 failed。成功后请尽快下载 content.video_url。
成功响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 字符串,平台任务 UUID。 |
model | string | 执行该任务时使用的模型名称及版本信息,具体格式以接口返回值为准。 |
status | string | queued、running、succeeded 或 failed。 |
created_at / updated_at | integer | 创建和更新时间,Unix 时间戳。 |
content | object | 生成结果容器。 |
content.video_url | string | 成功时的视频地址;请在有效期内下载。 |
content.last_frame_url | string | 尾帧图像 URL;创建时设置 return_last_frame: true 时返回。 |
duration | number | 实际输出视频时长(秒)。 |
ratio | string | 实际输出宽高比。 |
resolution | string | 实际输出分辨率。 |
output_format | string | 实际输出格式,如 mp4 或 mov。 |
framespersecond | integer | 输出视频帧率。 |
generate_audio | boolean | 是否生成音频。 |
seed | integer | 本次生成使用的随机种子。 |
usage | object | 任务用量信息。 |
usage.completion_tokens / usage.total_tokens | integer | 生成用量 token 数。 |
usage.tool_usage.web_search | integer | 联网搜索调用次数,仅开启联网搜索时返回。 |
execution_expires_after | integer | 任务执行有效期相关配置。 |
service_tier | string | 服务等级。 |
priority | integer | 任务优先级。 |
draft | boolean | 2.5 任务是否为样片,true 为样片,false 为正式视频。 |
draft_task_id | string | 2.5 复用样片时对应的平台样片任务 UUID。 |
tools | array | 本次任务实际使用的工具,未使用时不返回。 |
safety_identifier | string | 终端用户标识,创建时设置则原样返回。 |
失败响应
{
"id": "260e3207-aefd-4ca8-8f35-537a5990d172",
"model": "doubao-seedance-2-5-260628",
"status": "failed",
"error": {
"code": "OutputVideoSensitiveContentDetected",
"message": "The request failed because the output video may contain sensitive information. Request ID: task_xxx"
},
"created_at": 1718049470,
"updated_at": 1718049470
}失败响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 失败任务 ID。 |
model | string | 执行该任务时使用的模型名称及版本信息,具体格式以接口返回值为准。 |
status | string | 失败时为 failed。 |
error | object | 错误对象。 |
error.code | string | 错误码,例如 OutputVideoSensitiveContentDetected。 |
error.message | string | 错误说明。 |
created_at / updated_at | integer | 创建和更新时间,Unix 时间戳。 |
成功响应示例
以下为脱敏结构示例,任务 ID、模型版本、时间与产物地址均为占位值。
{
"id": "00000000-0000-4000-8000-000000000001",
"model": "ACTUAL_MODEL_VERSION",
"status": "succeeded",
"created_at": 1700000000,
"updated_at": 1700000060,
"content": {
"video_url": "https://example.com/generated-video.mp4"
},
"usage": {
"completion_tokens": 100,
"total_tokens": 100
}
}Seedance 2.5 成功示例
2.5 使用相同查询接口,以下为正式视频成功后的响应示例:
{
"id": "550e8400-e29b-41d4-a716-446655440025",
"model": "seedance-2.5",
"status": "succeeded",
"created_at": 1792800000,
"updated_at": 1792800060,
"content": {
"video_url": "https://media.example.com/generated/seedance25.mp4"
},
"resolution": "720p",
"ratio": "16:9",
"duration": 20,
"generate_audio": true,
"draft": false
}2.5 的参数或任务类型不兼容可能在受理后才报错,请查询至明确终态;不要仅凭创建返回 ID 判断生成成功。
任务状态
| 状态 | 含义 | 是否继续查询 |
|---|---|---|
queued | 排队中 | 是 |
running | 运行中 | 是 |
succeeded | 成功 | 否,获取产物 |
failed | 失败 | 否,处理错误 |
cancelled | 已取消 | 否 |
expired | 已超时 | 否 |
查询建议
为查询设置间隔、最大次数和总超时。不要在失败或超时后无限查询,也不要因为等待超时就自动提交一个新生成任务。
产物链接与下载
- 平台默认存储:视频和尾帧使用有效期为 24 小时的访问链接,从链接签发时起计算。 请在结果就绪后及时下载或保存到自己的存储。
- 重复查询:返回已保存的产物链接,不会因为再次查询而自动延长链接有效期。 任务记录可查询不代表产物链接仍可访问。
- 自定义存储:转存成功后,地址及访问权限由你的存储库配置决定,应保持存储库和文件可用。
本接口返回平台存储或自定义存储地址,不能把火山源产物 URL 的下载次数限制直接套用到这些地址。 请保存完整产物 URL,包括其查询参数;下载时不要自行拼接、截断签名参数或发送 API Key。
自定义存储状态
通过创建请求的 oss-id 指定自定义存储后,查询结果同时反映模型生成和产物转存两个进度。
custom_storage_status:PENDING待转存、PROCESSING转存中、SUCCESS转存成功、FAILED转存失败。can_retry_transfer:boolean。为true表示存在来源仍可访问的失败产物,可以重试转存。 该字段只说明重试条件,不会自动发起重试。transfer_source_expired:boolean。为true表示至少一个失败产物的来源已过期或无法下载。transfer_error_message:转存失败说明。
can_retry_transfer 和 transfer_source_expired 可能同时为 true,表示多个失败产物中, 部分仍可重试,部分来源已失效。没有失败产物时,transfer_source_expired 可能省略。
例如,模型已经生成成功、产物仍在转存时,可能返回:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"model": "seedance-2.0",
"status": "succeeded",
"created_at": 1792800000,
"updated_at": 1792800060,
"custom_storage_status": "PROCESSING",
"can_retry_transfer": false
}此时尚无可用产物 URL,请继续查询转存进度。若转存失败,请检查存储库配置并处理转存问题, 不要仅因转存失败自动创建新的视频生成任务。
查询失败与轮询建议
- HTTP 400:任务 UUID 或 Query 参数不符合要求。
- HTTP 401:密钥无效、停用或过期。
- HTTP 403:账户或 IP 白名单等认证条件不满足要求。
- HTTP 404:单任务不存在,或不属于当前 API Key 的可访问任务。
- HTTP 429:触发公共请求限流,降低查询频率后重试。
- HTTP 500、503:服务异常或任务结果暂不可用,保留任务 ID,稍后重试查询。
常见查询错误码为 InvalidParameter(参数不符合要求)、TaskNotFound(任务不可访问)和 TaskResultUnavailable(结果暂不可用)。认证错误及其处理方式见身份认证。
请求失败的错误体格式见错误处理。 任务 status=failed 表示已查询到一个失败任务,此时 HTTP 仍可为 200, 它与查询请求本身失败是两种情况。
建议从每隔 3~5 秒查询一次开始,遇到限流或暂不可用时逐步增加间隔。 客户端等待超时后,保留任务 ID 和 X-Request-ID,稍后恢复查询或联系支持排查, 不要将等待超时直接视为任务未受理或自动退款。 已收到成功响应并取得产物后应停止轮询;已收到 failed、cancelled 或 expired 时也应停止常规轮询。 查询请求失败时,先按 HTTP 错误处理,不要将 HTTP 错误码直接写入任务的 status。
协议参考
本平台的任务 ID、可见范围、响应字段及产物地址规则以本文为准。

