跳转到正文
阅读设置
Seedance 原生协议
GET/api/v3/contents/generations/tasks/{task_id}

查询任务 ​

GET /api/v3/contents/generations/tasks/{task_id}

请求参数 ​

参数位置参数类型必填说明
路径参数task_idstring是创建任务响应中的任务 ID。当前创建响应的 task_id 与 id 值相同。
请求头Authorizationstring是Bearer YOUR_API_KEY。
请求头Content-Typestring否建议设置为 application/json;GET 请求不需要请求体。
bash
curl -X GET /api/v3/contents/generations/tasks/task_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

成功响应 ​

json
{
	"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。

成功响应字段 ​

字段类型说明
idstring字符串,平台任务 UUID。
modelstring执行该任务时使用的模型名称及版本信息,具体格式以接口返回值为准。
statusstringqueued、running、succeeded 或 failed。
created_at / updated_atinteger创建和更新时间,Unix 时间戳。
contentobject生成结果容器。
content.video_urlstring成功时的视频地址;请在有效期内下载。
content.last_frame_urlstring尾帧图像 URL;创建时设置 return_last_frame: true 时返回。
durationnumber实际输出视频时长(秒)。
ratiostring实际输出宽高比。
resolutionstring实际输出分辨率。
output_formatstring实际输出格式,如 mp4 或 mov。
framespersecondinteger输出视频帧率。
generate_audioboolean是否生成音频。
seedinteger本次生成使用的随机种子。
usageobject任务用量信息。
usage.completion_tokens / usage.total_tokensinteger生成用量 token 数。
usage.tool_usage.web_searchinteger联网搜索调用次数,仅开启联网搜索时返回。
execution_expires_afterinteger任务执行有效期相关配置。
service_tierstring服务等级。
priorityinteger任务优先级。
draftboolean2.5 任务是否为样片,true 为样片,false 为正式视频。
draft_task_idstring2.5 复用样片时对应的平台样片任务 UUID。
toolsarray本次任务实际使用的工具,未使用时不返回。
safety_identifierstring终端用户标识,创建时设置则原样返回。

失败响应 ​

json
{
  "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
}

失败响应字段 ​

字段类型说明
idstring失败任务 ID。
modelstring执行该任务时使用的模型名称及版本信息,具体格式以接口返回值为准。
statusstring失败时为 failed。
errorobject错误对象。
error.codestring错误码,例如 OutputVideoSensitiveContentDetected。
error.messagestring错误说明。
created_at / updated_atinteger创建和更新时间,Unix 时间戳。

成功响应示例 ​

以下为脱敏结构示例,任务 ID、模型版本、时间与产物地址均为占位值。

json
{
  "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 使用相同查询接口,以下为正式视频成功后的响应示例:

json
{
  "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 可能省略。

例如,模型已经生成成功、产物仍在转存时,可能返回:

json
{
  "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、可见范围、响应字段及产物地址规则以本文为准。