核心指南

异步任务与状态查询

创建媒体任务,并等待最终结果

不少媒体端点会先返回任务,而不是直接返回成品。保存任务 ID,并调用 GET /v1/tasks/{id} 查询,直到状态变为 completed 或 failed。图片、视频、音乐、3D、Worlds 和异步音频转写任务都使用这一个端点。

异步任务终态快照的保留期限与 30 天的请求/响应记录期限分开计算。生成的图片、视频、音频、3D 和 Worlds 文件 URL 是 TokenLab 媒体结果 URL,有效期 30 天。已完成任务的状态查询约 7 天内有效,请在任务完成后立即保存结果。响应中的 media_retention 字段提供每项的保存状态和 expires_at;如果未能及时确定保存状态,该字段可能缺失,URL 仍可使用。失败或进行中的任务,其媒体 URL 字段为空。参见数据保留。

需要保存的字段

创建响应可以包括:

字段含义怎么处理
idTokenLab 任务 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 参考

主题参考
获取任务状态获取任务状态
取消任务取消任务
图像生成图像生成
视频生成视频生成
音乐生成音乐生成
3D 生成3D 生成
计费与定价计费与定价

任务终态后停止轮询;遇到 401、403、404 或不可重试错误也要停止。不想轮询时,可以用 mt-… 管理令牌配置 Webhook 管理 API,直接接收任务结果。

任务响应还带有 X-Task-ID、X-Task-Type 和 X-Billing-Transaction-ID 响应头,可以和任务 ID 一起记录。

本页内容