メインコンテンツへスキップ
多くのメディアエンドポイントは非同期です。作成リクエストは作業を開始し、公開TokenLabタスクのIDを返します。アプリケーションは、そのタスクが最終ステータスに達するまでポーリングします。上流タスクのURL、ルーティングID、またはプロバイダーのコールバック動作に基づいて顧客のワークフローを構築しないでください。

​
公開タスク契約

作成レスポンスには以下が含まれる場合があります：
フィールド意味何をするか
id公開TokenLabタスクID自分のジョブレコードと一緒に保存する
task_id同じ公開タスクIDの互換性エイリアスidと同等として扱う
status現在の公開タスクステータス最終でない場合はポーリングを開始する
poll_url推奨ステータスURL存在する場合はこれを最初に使用する
modelエンドポイントによって要求または解決されたモデルサポートおよび請求調整のために保存する
/v1/tasks/{id}は、公開非同期メディアジョブのための標準的な固定ステータスエンドポイントです。互換性のためにメディア特有のステータスルートが存在する場合がありますが、新しい統合はpoll_urlまたは/v1/tasks/{id}を優先するべきです。

​
推奨フロー

  1. ユーザーリクエストを検証し、明示的なmodelを持つ作成呼び出しを送信します。
  2. UIに制御を戻す前に、id / task_id、poll_url、エンドポイント、モデル、ユーザーID、および自分のジョブIDを保存します。
  3. 長時間実行されるメディアタスクのために、毎5-10秒ポーリングします。
  4. タスクがcompletedまたはfailedになるまで停止しません。
  5. completedの場合、メディア特有の結果フィールドを読み取り、最終URLまたはメタデータを保存します。
  6. 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などのキューに入ったVolcengine Seedanceビデオタスクをサポートしています。 サポートされていないタスクは400 unsupported_task_cancelを返します。すでに実行中または最終のタスクは409 task_not_cancellableを返します。キャンセルUIは「キャンセルをリクエスト」として構築し、保証された停止ボタンではなくします。

​
トラブルシューティング

症状考えられる原因確認すべきこと
async_task_not_foundタスクが不明、期限切れ、このAPIキーにアクセスできない、または公開非同期タスクでないAPIキーの所有権と保存された公開task_idを確認
タスクが完了しないクライアントが間違った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、または完全なプロンプトを含めないでください。

​
APIリファレンス

トピックリファレンス
タスクステータスの取得タスクステータスの取得
タスクのキャンセルタスクのキャンセル
画像生成画像生成
ビデオ生成ビデオ生成
音楽生成音楽生成
3D生成3D生成
請求と価格設定請求と価格設定