コアガイド

非同期ジョブとポーリング

メディアタスクを作成し、完了結果を待機する

多くのメディアエンドポイントは、完了したファイルではなくタスクを返します。返されたタスクIDを保存し、ステータスが completed または failed になるまで GET /v1/tasks/{id} をポーリングしてください。この単一のエンドポイントで、画像、動画、音楽、3D、Worlds、および非同期の音声文字起こしタスクを処理します。

非同期ターミナルタスクのスナップショットは、30日間のリクエスト/レスポンス保持期間とは別にライフサイクルを持ちます。生成された画像、動画、音声、3D、およびWorldsのファイルURLはTokenLabのメディア結果URLであり、30日間有効です。完了したタスクのステータス読み取りは約7日間有効ですので、タスクが完了したらすぐに結果を保存してください。レスポンスの media_retention フィールドには、各アイテムの保存状況と expires_at が報告されます。保存状況が時間内に判明しない場合、これらのフィールドは存在しないことがありますが、URLは引き続き機能します。失敗したタスクや進行中のタスクは、空のメディアURLフィールドを返します。データ保持を参照してください。

保存すべきフィールド

作成レスポンスには以下が含まれる場合があります:

フィールド意味対応方法
idTokenLabタスクID独自のジョブ記録と一緒に保存する
task_id同じタスクIDの別名id と同等として扱う
status現在のタスクステータス完了または失敗するまで確認を続ける
poll_urlタスクのステータスURL保存する。タスクIDを使用して /v1/tasks/{id} をポーリングする
modelタスクに使用されたモデルタスク記録と一緒に保存する

単一のステータスエンドポイント

作成レスポンスに含まれる id または task_id を使用して GET /v1/tasks/{id} をポーリングします。これはすべてのタスクタイプで機能します。ほとんどのタスクにおいて、poll_url はこのパスと同じです。Worldsの作成レスポンスは /v1/worlds/generations/{id} 配下の poll_url を返しますが、Worldsの場合もタスクの id を使用して /v1/tasks/{id} をポーリングしてください。

/v1/videos/generations/{id} のようなモダリティごとのステータスパスは、既存の統合のために引き続きサポートされます。新規の統合では /v1/tasks/{id} を使用してください。

タスクの保存とステータスの確認

作成リクエストが成功したらすぐに id または task_id を保存してください。あわせて poll_url、モデル、エンドポイント、および独自のユーザーIDやジョブ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 フィールドは、その文字列またはオブジェクトの形状を保持します。失敗したタスクには、status(ビジネスエラーのステータス)、type、code、message、param、retryable を含む error_details が含まれる場合があります。例えば、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 オブジェクトを使用します。同じべき等(idempotent)の作成リクエストを繰り返しても、その拒否状態は維持されます。失敗したステータス読み取りは、タスクのターミナル状態を変更しません。

重複タスクの回避

重複する生成のほとんどは、タイムアウト後に作成リクエストを再試行することによって発生します。

タイムアウトの発生場所より安全な動作
サーバーが作成レスポンスを受け取る前同じ Idempotency-Key を使用して同じリクエストを再送し、元のタスクを取得する。キーがない場合は request_id を確認し、タスクが作成されていない場合のみ再試行する
作成レスポンスが保存された後保存された task_id のポーリングを再開する
ポーリング中バックオフを伴うステータスリクエストの再試行を行う
ターミナルステータス後ユーザーが明示的にレコードを更新しない限り、再ポーリングしない

ブラウザの更新やステータスプールの失敗を理由に、2回目の作成リクエストを送信しないでください。

請求記録

非同期タスクは、受け入れられた時点で推定コストを予約する場合があります。最終的な金額は、タスクの完了または失敗後に記録されます。ステータスレスポンスには billing_transaction_id および X-Billing-Transaction-ID ヘッダーが含まれる場合があります。

以下の識別子をセットで管理してください:

  • 作成リクエストからの request_id
  • タスクからの task_id / id
  • 存在する場合の billing_transaction_id
  • 独自のユーザーID、プロジェクトID、またはジョブID

キャンセル

DELETE /v1/tasks/{id} は、seedance-2.0 や seedance-2.0-fast を含む、サポートされているSeedance動画タスクがキューに入っている間にキャンセルできます。

サポートされていないタスクは 400 unsupported_task_cancel を返します。すでに実行中または完了済みのタスクは 409 task_not_cancellable を返します。キャンセルはリクエストであり、進行中の作業が即座に停止することを保証するものではありません。キャンセルが成功すると 200 が返され、status: "failed"、cancelled: true、cancellation_status: "cancelled" となります。キャンセルされたタスクには課金されません。

トラブルシューティング

症状考えられる原因確認事項
404 async_task_not_foundタスクIDが不明、別のワークスペースのもの、または完了したタスクがステータス保持期間を過ぎている保存された task_id とAPIキーのワークスペースを確認する
403 task_not_owned現在のワークスペースでタスクの所有権を確認できないAPIキーに関連付けられたワークスペースまたは組織を確認する
503 async_task_owner_unavailable現在タスクの所有権を確認できない。retryable は trueバックオフを伴うステータスリクエストの再試行を行う
タスクが完了しないクライアントが誤ったURLをポーリングし続けている、またはターミナルステータス前に停止している保存されたタスクIDを使用して GET /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生成
請求と価格請求と価格

ターミナル状態のタスクのポーリングは停止してください。また、401、403、404、または再試行不可能なエラーが発生した場合も停止してください。ポーリングなしでタスク結果を受け取るには、mt-… 管理トークンを使用して Webhook管理API を設定してください。

タスクレスポンスには X-Task-ID、X-Task-Type、X-Billing-Transaction-ID ヘッダーも含まれており、これらをタスクIDと並べてログに記録できます。

このページの内容