核心指南
异步任务与状态查询
创建媒体任务,并等待最终结果
不少媒体端点会先返回任务,而不是直接返回成品。保存任务 ID,并调用 GET /v1/tasks/{id} 查询,直到状态变为 completed 或 failed。图片、视频、音乐、3D、Worlds 和异步音频转写任务都使用这一个端点。
异步任务终态快照的保留期限与 30 天的请求/响应记录期限分开计算。生成的图片、视频、音频、3D 和 Worlds 文件 URL 是 TokenLab 媒体结果 URL,有效期 30 天。已完成任务的状态查询约 7 天内有效,请在任务完成后立即保存结果。响应中的 media_retention 字段提供每项的保存状态和 expires_at;如果未能及时确定保存状态,该字段可能缺失,URL 仍可使用。失败或进行中的任务,其媒体 URL 字段为空。参见数据保留。
需要保存的字段
创建响应可以包括:
| 字段 | 含义 | 怎么处理 |
|---|---|---|
id | TokenLab 任务 ID | 与你自己的任务记录一起保存 |
task_id | 同一个任务 ID 的另一种字段名 | 与 id 等同处理 |
status | 当前状态 | 完成或失败前继续查询 |
poll_url | 任务的状态地址 | 可以保存;用任务 ID 调用 /v1/tasks/{id} 查询 |
model | 任务使用的模型 | 与任务记录一起保存 |
统一的状态端点
用创建响应中的 id 或 task_id 调用 GET /v1/tasks/{id}。所有任务类型都适用。多数任务的 poll_url 就是这个路径。Worlds 创建响应返回的 poll_url 位于 /v1/worlds/generations/{id};Worlds 也请用任务 id 调用 /v1/tasks/{id}。
按类型划分的状态路径(例如 /v1/videos/generations/{id})继续保留,供现有集成使用。新集成请使用 /v1/tasks/{id}。
保存任务并查询状态
创建成功后立即保存 id 或 task_id,同时记录 poll_url、模型、API 地址,以及你自己的用户或任务 ID。耗时较长的媒体任务通常每 5–10 秒查询一次即可。
状态变为 completed 或 failed 后停止查询。完成的任务会带回媒体结果;失败的任务会带回可记录或展示的错误。重新生成会创建一个新任务,也可能产生新的费用。
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"model": "veo3.1"
}查询示例
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
-H "Authorization: Bearer sk-your-api-key"任务状态包括 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。当 error_details.projection_version 为 2 时,message 是这次失败的最终原因,通常是上游服务自己的说明,例如参数限制或内容政策判定。任务运行在 Official 线路时,error_details.upstream 还会原样提供上游错误:message,以及已知时的 code、param 和 source(上游服务名称)。程序分支请继续使用 code 和 type;upstream.code 由上游服务定义,可能变化。
任务被接受前的创建拒绝,使用正常的 HTTP 错误状态与结构化 error 对象;使用相同幂等标识重放创建请求时会保留该拒绝。状态查询本身失败不会改变任务的最终状态。
避免重复生成
创建请求超时后直接重发,最容易产生重复任务。
| 超时发生位置 | 更安全的行为 |
|---|---|
| 服务端没有收到创建响应 | 用同一个 Idempotency-Key 原样重发,拿到原来的任务。没有带键时,用 request_id 查询,确认没有创建任务后再重试 |
| 已经保存创建响应 | 继续查询已保存的 task_id |
| 查询状态时超时 | 退避后重新查询状态,不要重新创建 |
| 已经完成或失败 | 不再自动查询 |
浏览器刷新或状态查询失败时,不要再次创建任务。
费用记录
异步任务被接受时可能暂扣预估费用,完成或失败后才会记录最终金额。状态响应可能包含 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-2.0 和 seedance-2.0-fast。
不支持取消时返回 400 unsupported_task_cancel;任务已经开始或结束时返回 409 task_not_cancellable。取消请求不保证已经开始的任务一定能停下。取消成功时返回 200,带有 status: "failed"、cancelled: true 和 cancellation_status: "cancelled"。被取消的任务不收费。
故障排除
| 症状 | 可能原因 | 检查内容 |
|---|---|---|
404 async_task_not_found | 任务 ID 不存在、属于其他工作区,或已完成的任务已超过状态查询期限 | 检查保存的 task_id 和 API 密钥所属的工作区 |
403 task_not_owned | 无法确认任务属于当前工作区 | 确认 API 密钥关联的工作区或组织 |
503 async_task_owner_unavailable | 暂时无法核对任务归属,retryable 为 true | 退避后重试状态查询 |
| 长时间没有完成 | 查询地址错误,或过早停止查询 | 用保存的任务 ID 调用 GET /v1/tasks/{id},查看最新状态 |
| 完成后没有媒体 URL | 任务仍未完成,或完成时没有可用文件 | 查询到最终状态;没有结果时按失败处理 |
| 用户看到重复结果 | 超时或刷新后又创建了一次 | 用自己的任务 ID 和 task_id 去重 |
| 账单金额对不上 | 最终费用尚未记录,或比较了错误的 ID | 对照 request_id、task_id 和 billing_transaction_id |
联系支持时提供什么
请提供 request_id、task_id、billing_transaction_id(如有)、API 地址、模型、时间,以及请求中使用了哪些字段。不要发送 API 密钥、私密媒体、签名 URL 或完整提示词;支持人员明确需要时,也只发送脱敏示例。
API 参考
任务终态后停止轮询;遇到 401、403、404 或不可重试错误也要停止。不想轮询时,可以用 mt-… 管理令牌配置 Webhook 管理 API,直接接收任务结果。
任务响应还带有 X-Task-ID、X-Task-Type 和 X-Billing-Transaction-ID 响应头,可以和任务 ID 一起记录。