コアガイド
非同期ジョブとポーリング
非同期メディアジョブを作成し、公開TokenLabタスクのステータスをポーリングし、プロバイダー固有のIDなしで最終結果を調整します。
多くのメディアエンドポイントは非同期です。作成リクエストは作業を開始し、公開TokenLabタスクのIDを返します。アプリケーションは、そのタスクが最終ステータスに達するまでポーリングします。上流タスクのURL、ルーティングID、またはプロバイダーのコールバック動作に基づいて顧客のワークフローを構築しないでください。
公開タスク契約
作成レスポンスには以下が含まれる場合があります：
| フィールド | 意味 | 何をするか |
|---|---|---|
id | 公開TokenLabタスクID | 自分のジョブレコードと一緒に保存する |
task_id | 同じ公開タスクIDの互換性エイリアス | idと同等として扱う |
status | 現在の公開タスクステータス | 最終でない場合はポーリングを開始する |
poll_url | 推奨ステータスURL | 存在する場合はこれを最初に使用する |
model | エンドポイントによって要求または解決されたモデル | サポートおよび請求調整のために保存する |
/v1/tasks/{id}は、公開非同期メディアジョブのための標準的な固定ステータスエンドポイントです。互換性のためにメディア特有のステータスルートが存在する場合がありますが、新しい統合はpoll_urlまたは/v1/tasks/{id}を優先するべきです。
推奨フロー
- ユーザーリクエストを検証し、明示的な
modelを持つ作成呼び出しを送信します。 - UIに制御を戻す前に、
id/task_id、poll_url、エンドポイント、モデル、ユーザーID、および自分のジョブIDを保存します。 - 長時間実行されるメディアタスクのために、毎
5-10秒ポーリングします。 - タスクが
completedまたはfailedになるまで停止しません。 completedの場合、メディア特有の結果フィールドを読み取り、最終URLまたはメタデータを保存します。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"が含まれるため、古いステータス処理が機能し続けます。
クライアント再試行ルール
ネットワークタイムアウトは、重複ジョブの最も一般的な原因です。このルールを使用してください：
| タイムアウトが発生する場所 | より安全な動作 |
|---|---|
| サーバーが作成レスポンスを受信する前 | 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-1.5-pro、seedance-2.0、seedance-2.0-fast などのキュー中の Seedance 動画タスクに対応します。
サポートされていないタスクは400 unsupported_task_cancelを返します。すでに実行中または最終のタスクは409 task_not_cancellableを返します。キャンセルUIは「キャンセルをリクエスト」として構築し、保証された停止ボタンではなくします。
トラブルシューティング
| 症状 | 考えられる原因 | 確認すべきこと |
|---|---|---|
404 async_task_not_found | タスクの期限が切れたか、利用できなくなった | 保存した task_id と poll_url を確認 |
403 task_not_owned | 現在のワークスペースにタスクが属することを確認できない | API キーに紐づくワークスペースまたは組織を確認 |
| タスクが完了しない | クライアントが間違ったURLをポーリングし続けるか、最終ステータスの前に停止した | poll_urlまたは/v1/tasks/{id}を使用し、最新のステータスを確認 |
| 最終メディアURLが欠落 | タスクが完了していないか、上流ジョブが使用可能な出力なしで完了した | 最終までポーリングし、欠落した出力を失敗として処理 |
| ユーザーが重複を確認 | 再試行パスがタイムアウトまたはリフレッシュ後に新しいタスクを作成した | 自分のジョブIDと保存されたtask_idで重複を排除 |
| 請求の不一致 | 決済が非同期であるか、クライアントがプロバイダーIDを比較している | request_id、task_id、およびbilling_transaction_idを比較 |
サポートパケット
サポートに連絡する際は、request_id、task_id、billing_transaction_id（存在する場合）、エンドポイント、モデル、タイムスタンプ、およびサニタイズされたリクエスト形状を含めてください。サポートが赤actedサンプルを要求しない限り、APIキー、プライベートメディア、署名付きURL、または完全なプロンプトを含めないでください。