> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 非同期メディアジョブを作成し、公開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}`を優先するべきです。

## 推奨フロー

1. ユーザーリクエストを検証し、明示的な`model`を持つ作成呼び出しを送信します。
2. UIに制御を戻す前に、`id` / `task_id`、`poll_url`、エンドポイント、モデル、ユーザーID、および自分のジョブIDを保存します。
3. 長時間実行されるメディアタスクのために、毎`5-10秒`ポーリングします。
4. タスクが`completed`または`failed`になるまで停止しません。
5. `completed`の場合、メディア特有の結果フィールドを読み取り、最終URLまたはメタデータを保存します。
6. `failed`の場合、公開エラーを保存し、新しいユーザー可視ジョブとしてのみ再試行を提供します。

```json theme={null}
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}
```

## ポーリングの例

```bash theme={null}
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リファレンス

| トピック        | リファレンス                                                 |
| ----------- | ------------------------------------------------------ |
| タスクステータスの取得 | [タスクステータスの取得](/ja/api-reference/tasks/get-task-status) |
| タスクのキャンセル   | [タスクのキャンセル](/ja/api-reference/tasks/cancel-task)       |
| 画像生成        | [画像生成](/ja/guides/image-generation)                    |
| ビデオ生成       | [ビデオ生成](/ja/guides/video-generation)                   |
| 音楽生成        | [音楽生成](/ja/guides/music-generation)                    |
| 3D生成        | [3D生成](/ja/guides/3d-generation)                       |
| 請求と価格設定     | [請求と価格設定](/ja/guides/billing)                          |