# 非同期タスク
> Agent タスクのライフサイクル、Task envelope、ポーリング、コールバック、キャンセル。

1 回の HTTP 往復を超える Agent skills は `202` + Task envelope を返します。
タスクはキューに入り、非同期で実行され、ポーリングまたはコールバックで観測できます：

```text
queued → running → succeeded | failed | canceled
```

## Task envelope

作成時のレスポンス、`GET /v1/tasks/{task_id}`、コールバックの POST body の 3 か所すべてで**同一の構造**が返ります：

| フィールド | 説明 |
| --- | --- |
| `task_id` | `task_` プレフィックス付きタスク ID。冪等リトライでは同じ ID |
| `status` | `queued / running / succeeded / failed / canceled` |
| `capability` | 機能名。例：`text_to_video` または `social_data_fetch` |
| `workload_type` | メディア/理解は `model`、公開ソーシャルデータ読み取りは `social_operation` |
| `model` / `resolved_model` | リクエストしたモデル（`auto` も可）/ 実際に実行したモデル。`social_operation` では null |
| `social` | ソーシャル Task に付く：`platform`、`operation_key`、`operation_name`、`schema_hash` |
| `input` | 正規化された入力のエコーバック |
| `output` | 生成物。`succeeded` のときのみ存在。構造は各機能ページを参照 |
| `progress` | `{ percent, stage, message }`。実行中のみ意味を持つ |
| `warnings[]` | 予約フィールド。現在は常に空リスト |
| `error` | `{ code, message, retryable }`。`failed` のときのみ存在 |
| `usage` / `billing` | 課金の明細 → [課金と使用量](https://docs.beatra.ai/ja/docs/mechanisms/billing) |
| `callback` | コールバックの配信状態 → [コールバック](https://docs.beatra.ai/ja/docs/mechanisms/callbacks) |
| `metadata` | 予約フィールド。作成時に受け付けますが、現在レスポンスでは常に `null` |
| `created_at / started_at / completed_at` | ライフサイクルのタイムスタンプ（UTC） |
| `links` | `{ self, cancel }` |

## ポーリング・一覧・キャンセル

| 操作 | エンドポイント | 説明 |
| --- | --- | --- |
| 単一取得 | `GET /v1/tasks/{task_id}` | 完全な envelope を返す。5 秒間隔で終了状態までポーリングするのを推奨 |
| 一覧 | `GET /v1/tasks?limit=100` | カーソルページネーションのサマリー。output/usage は**含まない** |
| キャンセル | `POST /v1/tasks/{task_id}/cancel` | 冪等。終了済みタスクはそのまま返し、実行中は停止が確認された場合のみキャンセルに成功する |

リモート実行の開始前は、キャンセルによってタスクを停止し、前払いクレジットを返却します。実行開始後、停止が確認された場合にのみ Beatra は `canceled` を返します。`409` はタスクが継続していることを示します。停止や返金を約束せず、代替タスクを送信せず、同じタスクのポーリングを終端状態まで継続してください。

MiniMax H3 は上流タスクが `queued` の間だけキャンセルを確認できます。
`running` に入った後は Beatra が `409` を返し、返金しません。この場合、
確認済みキャンセルを意味しない上流 DELETE は呼び出しません。

## 明示モデル vs `auto`

- 明示指定した `model` が**黙って置き換えられることはありません**。対応しない
  パラメータがあれば、リクエストは直ちに `422 unsupported_option` で失敗し、
  フィールド名を示します。
- `model: "auto"` では、具体的なモデルの選択と切り替えはプラットフォームの
  設計上の責務です。終端状態のタスクの `resolved_model` が実際に実行された
  モデルを記録します。

公開ソーシャルデータのタスクも制作と同様に前払いです。`beatra.social.execute` 1 回でタスク 1 件、照会 1 回です。照会開始後のキャンセルは `409` になり、同じタスクをポーリングし続けます。

## 生成ファイルの取得に時間がかかる場合

モデルの完了後、Beatra は上流から生成ファイルをダウンロードして保存してから、タスクを成功にします。その間 `progress.stage` は `finalizing` です。上流のファイル配信が失敗し続ける場合、Beatra は最大約 40 分にわたって数回再試行します。再生成や二重課金はなく、その間タスクは `running` のままです。それでも取得できない場合、タスクは `model_output_invalid` で失敗し、クレジットは返却されます。同じタスクのポーリングを続けてください。再送信すると、別途課金される 2 つ目のタスクが作成されます。

## 生成物の保存

`output` 内のリソース URL は CDN の URL です。**結果を取得したら速やかに自分のストレージへ保存**し、永続リンクとして扱わないでください。