TokenLab Seedance 任务取消与排队作业计费指南

视频生成任务是异步的。当您通过 POST /v1/videos/generations 提交视频生成请求时，TokenLab 会返回任务标识符并将作业加入队列。如果请求系误提交、在网络重试期间被重复提交或被最终用户放弃，在任务仍处于排队状态时取消任务可以避免不必要的计算与生成费用。

本指南将介绍如何调用任务取消端点、处理 API 响应码，以及管理计费预留与轮询状态流转。

任务取消的工作原理

任务取消针对的是仍处于 pending 排队状态的异步作业。一旦模型 worker 开始生成帧（任务状态流转为 processing）或任务达到终态（completed 或 failed），将无法再执行取消操作。

TokenLab 支持对排队中的 Seedance 视频模型进行取消，包括 seedance-2.0、seedance-2.0-fast 和 seedance-2.5。有关使用火山引擎兼容端点的集成，请参阅 Volc 兼容任务取消参考。

任务生命周期状态

• pending：任务已入队，正在等待可用 worker。在此时间窗口内支持取消。
• processing：模型已开始执行。取消请求将被拒绝。
• completed：视频生成成功完成。结果已就绪。
• failed：任务遇到错误或在执行前被取消。

扣费与预留语义

根据 TokenLab 的计费与定价指南，异步媒体作业的计费采用两阶段预留与结算模型：

1. 预授权 / 预留：当异步视频任务被接收时，TokenLab 可能会根据所选模型和参数冻结或预留预估金额。
2. 结算：最终费用仅在任务达到 completed 状态时进行结算。已完成的任务会附带一个表示最终账本条目的 billing_transaction_id。
3. 取消与失败：以 failed 状态结束的任务（包括在排队时被取消的任务）均不扣费。任何未使用的预留或临时冻结金额都将退还至您的工作区余额。

由于在队列中取消的任务从未完成生成，因此不会产生已完成的计费结算。

通过 API 取消排队中的任务

若要取消任务，请使用创建任务时返回的任务 ID 向 /v1/tasks/{id} 发送 DELETE 请求。有关完整的模式规范详情，请查阅取消任务 API 参考。

请求示例

curl -X DELETE "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

成功响应（HTTP 200）

当任务在开始执行前被成功取消时，API 将返回 HTTP 200。任务状态直接流转为 failed，并标记为 cancelled: true：

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "failed",
  "cancelled": true,
  "cancellation_status": "cancelled",
  "error": "Task cancelled before execution"
}

错误码与拒绝处理

不要假定 DELETE 调用总是成功。您的应用程序必须处理特定的 HTTP 错误状态：

HTTP 状态	错误码	含义	建议操作
400	unsupported_task_cancel	该模型或任务类型不支持取消。	让任务正常执行完毕，或检查模型支持情况。
403	task_not_owned	该 API 密钥不拥有此任务。	验证工作区凭据和 API 密钥权限范围。
404	async_task_not_found	任务 ID 不存在或已过期。	确认本地队列数据库中存储的任务 ID。
409	task_not_cancellable	任务已开始进入 processing 阶段，或已处于终态（completed/failed）。	接受生成已在进行中的事实；不要循环重试删除调用。

轮询已取消的任务

通过 GET /v1/tasks/{id} 或返回的 poll_url（如异步作业与轮询指南中所述）轮询任务时，请注意以下行为：

1. 终态任务返回 HTTP 200：读取已失败或已取消任务的状态时会返回 HTTP 200。请检查 JSON 响应体中的 status 和 cancelled 字段，而不是仅依赖 HTTP 响应码。
2. 状态识别：已取消的任务将显示 "status": "failed"、"cancelled": true 和 "cancellation_status": "cancelled"。
3. 不存在结算 ID：由于未发生扣费结算，已取消的任务不会包含 billing_transaction_id。

import time
import requests

def cancel_and_verify(task_id: str, api_key: str):
    url = f"https://api.tokenlab.sh/v1/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    # Attempt cancellation
    cancel_res = requests.delete(url, headers=headers)
    if cancel_res.status_code == 200:
        data = cancel_res.json()
        if data.get("cancelled"):
            print(f"Task {task_id} successfully cancelled.")
            return True
    elif cancel_res.status_code == 409:
        print(f"Task {task_id} already in progress or terminal; cannot cancel.")
    else:
        print(f"Cancellation rejected with HTTP {cancel_res.status_code}: {cancel_res.text}")

    # Poll task to determine terminal state
    poll_res = requests.get(url, headers=headers)
    if poll_res.ok:
        status_data = poll_res.json()
        print(f"Current status: {status_data.get('status')}, cancelled: {status_data.get('cancelled', False)}")
    return False

生产队列集成清单

在将 Seedance 视频工作流集成到 worker 架构中时，请遵循以下最佳实践：

• 立即持久化 ID：在分派下游工作之前，保存 POST /v1/videos/generations 响应中的 id（或 task_id）和 poll_url。
• 提交时去重：在创建任务之前，对客户端双击和上游网络重试进行去重，以防止意外生成任务。
• 将 409 视为非致命错误：如果取消请求返回 409 task_not_cancellable，请将其视为处理已开始的指示。降级处理为等待结果，若不再需要则直接丢弃输出。
• 解析取消标记：在轮询循环中，同时检查 status == "failed" 和 cancelled is True，以区分用户发起的取消与基础设施错误。
• 使用交易 ID 对账：仅在已完成的作业中存在 billing_transaction_id 时进行存储。对于已取消或失败的任务，不要预期存在交易 ID。

有关其他集成模式，请参阅视频生成指南和获取视频状态 API 参考。