コアガイド
非同期ジョブとポーリング
メディアタスクを作成し、完了結果を待機する
多くのメディアエンドポイントは、完了したファイルではなくタスクを返します。返されたタスクIDを保存し、ステータスが completed または failed になるまで GET /v1/tasks/{id} をポーリングしてください。この単一のエンドポイントで、画像、動画、音楽、3D、Worlds、および非同期の音声文字起こしタスクを処理します。
非同期ターミナルタスクのスナップショットは、30日間のリクエスト/レスポンス保持期間とは別にライフサイクルを持ちます。生成された画像、動画、音声、3D、およびWorldsのファイルURLはTokenLabのメディア結果URLであり、30日間有効です。完了したタスクのステータス読み取りは約7日間有効ですので、タスクが完了したらすぐに結果を保存してください。レスポンスの media_retention フィールドには、各アイテムの保存状況と expires_at が報告されます。保存状況が時間内に判明しない場合、これらのフィールドは存在しないことがありますが、URLは引き続き機能します。失敗したタスクや進行中のタスクは、空のメディアURLフィールドを返します。データ保持を参照してください。
保存すべきフィールド
作成レスポンスには以下が含まれる場合があります:
| フィールド | 意味 | 対応方法 |
|---|---|---|
id | TokenLabタスク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リファレンス
ターミナル状態のタスクのポーリングは停止してください。また、401、403、404、または再試行不可能なエラーが発生した場合も停止してください。ポーリングなしでタスク結果を受け取るには、mt-… 管理トークンを使用して Webhook管理API を設定してください。
タスクレスポンスには X-Task-ID、X-Task-Type、X-Billing-Transaction-ID ヘッダーも含まれており、これらをタスクIDと並べてログに記録できます。