TokenLab Seedanceタスクキャンセルとキュー待ちジョブの請求ガイド

動画生成タスクは非同期で実行されます。POST /v1/videos/generations 経由で動画生成リクエストを送信すると、TokenLabはタスク識別子を返し、ジョブをキューに追加します。誤ってリクエストを送信した場合、ネットワークの再試行によって重複した場合、またはエンドユーザーが処理を中断した場合、タスクがキューに残っている間にキャンセルすることで、不要なコンピュートおよび生成費用の発生を防ぐことができます。

本ガイドでは、タスクキャンセルエンドポイントの呼び出し方法、APIレスポンスコードの処理、請求の仮押さえ（予約）およびポーリング時のステータス遷移の管理方法について説明します。

タスクキャンセルの仕組み

タスクキャンセルは、まだキュー内で pending 状態にある非同期ジョブを対象としています。モデルワーカーがフレーム生成を開始する（タスクが processing に遷移する）か、またはタスクが終端状態（completed または failed）に達した後は、キャンセルを実行できません。

TokenLabは、seedance-2.0、seedance-2.0-fast、seedance-2.5 を含む、キューに入っているSeedance動画モデルのキャンセルをサポートしています。Volcengine互換エンドポイントを使用した連携については、Volc互換タスクキャンセルリファレンス を参照してください。

タスクのライフサイクル状態

• pending: タスクはキューに入れられ、利用可能なワーカーを待機しています。この期間中はキャンセルがサポートされます。
• processing: モデルの実行が開始されました。キャンセルリクエストは拒否されます。
• completed: 動画生成が正常に完了しました。結果の取得が可能です。
• failed: タスクでエラーが発生したか、実行前にキャンセルされました。

請求と仮押さえ（予約）のセマンティクス

TokenLabの請求および料金ガイドによると、非同期メディアジョブの請求は、予約（仮押さえ）と決済の2段階モデルに従います:

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 が返されます。HTTPレスポンスコードに依存するのではなく、JSONボディの status フィールドと cancelled フィールドを検査してください。
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リファレンス をご確認ください。