TokenLab Seedance 任務取消與排隊作業計費指南

影片生成任務為非同步作業。當您透過 POST /v1/videos/generations 提交影片生成請求時，TokenLab 會返回任務識別碼並將該作業排入佇列。若請求為誤提交、在網路重試期間重複發送，或已被終端使用者放棄，在任務仍處於排隊狀態時將其取消，可避免不必要的運算與生成費用。

本指南說明如何呼叫任務取消端點、處理 API 回應碼，以及管理計費預扣與輪詢狀態轉移。

任務取消的運作方式

任務取消主要針對仍處於 pending 排隊狀態的非同步作業。一旦模型工作節點開始生成影格（將任務狀態轉移至 processing），或者任務達到終態（completed 或 failed），便無法再進行取消。

TokenLab 支援對排隊中的 Seedance 影片模型進行取消，包括 seedance-2.0、seedance-2.0-fast 以及 seedance-2.5。針對使用火山引擎相容端點的整合，請參閱 Volc 相容任務取消參考文件。

任務生命週期狀態

• pending：任務已排入佇列，正在等待可用的工作節點。在此期間支援取消。
• processing：模型已開始執行。此時取消請求將會被拒絕。
• completed：影片生成已成功完成。結果已就緒。
• failed：任務遇到錯誤，或在執行前已被取消。

計費與預扣語意

根據 TokenLab 的計費與定價指南，非同步媒體作業的計費採用兩階段預扣與結算模式：

1. 預先授權／預扣（Reservation）：當非同步影片任務被接受時，TokenLab 可能會根據所選模型及參數暫扣或預留預估金額。
2. 結算（Settlement）：僅當任務達到 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）。	接受生成作業已在進行中；切勿在迴圈中重試 delete 呼叫。

輪詢已取消的任務

透過 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 影片工作流程整合至工作架構時，請遵循以下最佳實踐：

• 立即持久化儲存 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 參考文件。