核心指南
异步任务与状态查询
创建媒体任务，并等待最终结果
不少媒体端点会先返回任务，而不是直接返回成品。保存任务 ID，并使用 poll_url 查询，直到状态变为 completed 或 failed。
需要保存的字段
创建响应可以包括：
| 字段 | 含义 | 怎么处理 |
|---|---|---|
id | TokenLab 任务 ID | 与你自己的任务记录一起保存 |
task_id | 同一个任务 ID 的另一种字段名 | 与 id 等同处理 |
status | 当前状态 | 完成或失败前继续查询 |
poll_url | 状态查询地址 | 返回时直接使用 |
model | 任务使用的模型 | 与任务记录一起保存 |
响应中有 poll_url 时直接使用。客户端需要固定地址时，可以调用 /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 对象；使用相同幂等标识重放创建请求时会保留该拒绝。状态查询本身失败不会改变任务的最终状态。
避免重复生成
创建请求超时后直接重发，最容易产生重复任务。
| 超时发生位置 | 更安全的行为 |
|---|---|
| 服务端没有收到创建响应 | 用 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-1.5-pro、seedance-2.0 和 seedance-2.0-fast。
不支持取消时返回 400 unsupported_task_cancel；任务已经开始或结束时返回 409 task_not_cancellable。取消请求不保证已经开始的任务一定能停下。
故障排除
| 症状 | 可能原因 | 检查内容 |
|---|---|---|
404 async_task_not_found | 任务已过期或已不可用 | 检查保存的 task_id 和 poll_url |
403 task_not_owned | 无法确认任务属于当前工作区 | 确认 API 密钥关联的工作区或组织 |
| 长时间没有完成 | 查询地址错误，或过早停止查询 | 使用 poll_url 或 /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 参考
通过 Webhook 管理 API 配置任务通知。使用 mt-… 管理令牌；MCP full 模式通过 TOKENLAB_MANAGEMENT_TOKEN 配置。任务终态、401/403/404 或不可重试错误后停止轮询。