Skip to main content
不少媒体端点会先返回任务,而不是直接返回成品。保存任务 ID,并使用 poll_url 查询,直到状态变为 completed 或 failed。

需要保存的字段

创建响应可以包括: 响应中有 poll_url 时直接使用。客户端需要固定地址时,可以调用 /v1/tasks/{id}。

保存任务并查询状态

创建成功后立即保存 id 或 task_id,同时记录 poll_url、模型、API 地址,以及你自己的用户或任务 ID。耗时较长的媒体任务通常每 5–10 秒查询一次即可。 状态变为 completed 或 failed 后停止查询。完成的任务会带回媒体结果;失败的任务会带回可记录或展示的错误。重新生成会创建一个新任务,也可能产生新的费用。

查询示例

任务状态包括 pending、processing、completed 和 failed。取消后的任务使用 failed,同时带有 cancelled: true 和 cancellation_status: "cancelled"。 成功读取状态时,即使任务已经失败,HTTP 状态仍为 200。请使用任务的 status 判断生成结果。error 字段保持原有字符串或错误对象形式。失败任务还可能包含 error_details:其中 status 表示业务错误状态,另有 type、code、message、param 和 retryable。例如 error_details.status: 400、param: "size" 表示需要修改尺寸参数,并不表示本次状态查询失败。无法确定具体字段时会省略 param。 任务被接受前的创建拒绝,使用正常的 HTTP 错误状态与结构化 error 对象;使用相同幂等标识重放创建请求时会保留该拒绝。状态查询本身失败不会改变任务的最终状态。

避免重复生成

创建请求超时后直接重发,最容易产生重复任务。 浏览器刷新或状态查询失败时,不要再次创建任务。

费用记录

异步任务被接受时可能暂扣预估费用,完成或失败后才会记录最终金额。状态响应可能包含 billing_transaction_id 和 X-Billing-Transaction-ID 响应头。 请把下面几个 ID 保存在同一条记录中:
  • 来自创建请求的 request_id。
  • 来自任务的 task_id / id。
  • 当存在时的 billing_transaction_id。
  • 你自己的用户 ID、项目 ID 或作业 ID。

取消

DELETE /v1/tasks/{id} 可以取消仍在排队、并且支持取消的 Seedance 视频任务,包括 seedance-1.5-pro、seedance-2.0 和 seedance-2.0-fast。 不支持取消时返回 400 unsupported_task_cancel;任务已经开始或结束时返回 409 task_not_cancellable。取消请求不保证已经开始的任务一定能停下。

故障排除

联系支持时提供什么

请提供 request_id、task_id、billing_transaction_id(如有)、API 地址、模型、时间,以及请求中使用了哪些字段。不要发送 API 密钥、私密媒体、签名 URL 或完整提示词;支持人员明确需要时,也只发送脱敏示例。

API 参考