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 或完整提示词;支持人员明确需要时,也只发送脱敏示例。