外观
异步任务指南
图片异步生成、视频生成和素材审核通常不会在创建请求中直接返回最终结果。客户端需要保存任务 ID，并通过回调或查询接口等待终态。
标准流程
- 调用创建接口。
- 保存响应中的
id或task_id。 - 仅当具体接口支持回调且已配置
callback_url时，优先等待回调；否则按接口限制轮询。 - 识别成功、失败、取消和仍在处理中的状态。
- 成功后及时保存结果 URL 或业务结果。
状态分类
不同接口的状态名称不完全一致，应按页面和 OpenAPI 定义处理。
| 分类 | 常见状态 | 客户端行为 |
|---|---|---|
| 等待或处理中 | pending、queued、running、processing | 继续等待，不重复创建任务。 |
| 成功 | success、succeeded、completed | 读取并保存结果。 |
| 失败 | failure、failed | 记录错误信息，根据失败原因决定是否重新创建。 |
| 取消 | cancelled、canceled | 停止轮询，不默认重试。 |
轮询
- 使用创建接口返回的任务 ID，不要自行拼接或替换 ID。
- 遵守具体页面的最低查询间隔。
- 查询请求失败或受到限流时，优先遵守响应中的
Retry-After；任何退避时间都不得短于具体页面规定的最低查询间隔。 - 1 秒、2 秒、4 秒仅适用于未规定更长最低查询间隔的接口。Seedance-2 的最低查询间隔为 60 秒，其退避等待不得低于 60 秒。
- 达到业务最大等待时间后停止轮询，并将任务保留为待确认状态。
- 查询接口通常可以安全重试，创建接口不能默认安全重试。
回调
- 只有具体接口明确支持回调时才能配置
callback_url。 - 回调地址必须可以从公网访问。
- 收到回调后仍应校验任务 ID 和终态。
- 回调处理需要幂等，同一任务的重复回调不能重复发货或重复入库。
- 回调长时间未到达时，可以使用查询接口兜底。
创建请求重试
创建请求超时不代表服务端一定没有创建任务。自动重试前应先检查：
- 响应或日志中是否已经获得任务 ID。
- 服务端是否支持幂等键。
- 是否可以通过业务跟踪 ID 查询原请求。
无法确认时，不要无限重试创建接口，以免产生重复任务和重复计费。
结果保存
生成结果 URL 和签名下载地址通常有有效期。任务成功后应及时下载或转存到自己的存储系统。需要长期引用的业务标识，例如审核返回的 Asset://，应与临时下载 URL 区分保存。
失败排查
记录以下信息：
- 创建接口路径和任务 ID。
- HTTP 状态码和业务状态。
request_id、X-Trace-ID或X-Track-Id。- 最后一次查询时间和错误消息。
不要记录完整 API Key 或访问令牌。