跳转到主要内容
许多媒体端点是异步的。创建请求开始工作并返回公共 TokenLab 任务标识；您的应用程序轮询直到该任务达到终止状态。请勿围绕上游任务 URL、路由 ID 或提供商回调行为构建客户工作流。

​
公共任务契约

创建响应可以包括：
字段含义操作
id公共 TokenLab 任务 ID将其与您自己的作业记录一起存储
task_id相同公共任务标识的兼容别名将其视为与 id 等效
status当前公共任务状态当状态不是终止时开始轮询
poll_url优选状态 URL存在时优先使用此 URL
model端点请求或解析的模型存储以便支持和计费对账
/v1/tasks/{id} 是公共异步媒体作业的规范固定状态端点。可能存在特定于媒体的状态路由以保持兼容性，但新的集成应优先使用 poll_url 或 /v1/tasks/{id}。

​
推荐流程

  1. 验证用户请求并发送带有显式 model 的创建调用。
  2. 在将控制权返回给 UI 之前，持久化 id / task_id、poll_url、端点、模型、用户 ID 和您自己的作业 ID。
  3. 对于长时间运行的媒体任务，每 5-10s 轮询一次。
  4. 仅在任务为 completed 或 failed 时停止。
  5. 在 completed 时，读取特定于媒体的结果字段并存储最终 URL 或元数据。
  6. 在 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"，以便旧的状态处理继续有效。

​
客户端重试规则

网络超时是重复作业的最常见来源。使用以下规则：
超时发生位置更安全的行为
在您的服务器接收到创建响应之前检查服务器日志中的 request_id；仅在未创建任务时重试
在存储创建响应之后恢复对存储的 task_id 的轮询
在轮询期间使用退避重试状态请求
在终止状态之后除非用户明确刷新记录，否则不要再次轮询
不要仅因为浏览器刷新或状态轮询失败而发送第二个创建请求。

​
计费与结算

异步作业在创建请求被接受时可以保留估计金额。最终结算发生在终止状态之后。当可用时，任务状态响应可以暴露 billing_transaction_id 和 X-Billing-Transaction-ID 头。 对于对账，请在您的日志中连接这些标识符：
  • 来自创建请求的 request_id。
  • 来自任务的 task_id / id。
  • 当存在时的 billing_transaction_id。
  • 您自己的用户 ID、项目 ID 或作业 ID。

​
取消

DELETE /v1/tasks/{id} 是故意狭窄的。它当前支持排队的 Volcengine Seedance 视频任务，如 seedance-1.5-pro、seedance-2.0 和 seedance-2.0-fast。 不支持的任务返回 400 unsupported_task_cancel。已经运行或处于终止状态的任务返回 409 task_not_cancellable。构建取消 UI 时应为“请求取消”，而不是保证停止按钮。

​
故障排除

症状可能原因检查内容
async_task_not_found任务未知、过期、对该 API 密钥不可访问或不是公共异步任务确认 API 密钥所有权和存储的公共 task_id
任务似乎从未完成客户端一直在轮询错误的 URL 或在终止状态之前停止使用 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 密钥、私人媒体、签名 URL 或完整提示。

​
API 参考

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