非同期タスク
Agent タスクのライフサイクル、Task envelope、ポーリング、コールバック、キャンセル。
1 回の HTTP 往復を超える Agent skills は 202 + Task envelope を返します。
タスクはキューに入り、非同期で実行され、ポーリングまたはコールバックで観測できます：
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 |
model / resolved_model | リクエストしたモデル（auto も可）/ 実際に実行したモデル |
input | 正規化された入力のエコーバック |
output | 生成物。succeeded のときのみ存在。構造は各機能ページを参照 |
progress | { percent, stage, message }。実行中のみ意味を持つ |
warnings[] | 予約フィールド。現在は常に空リスト |
error | { code, message, retryable }。failed のときのみ存在 |
usage / billing | 課金の明細 → 課金と使用量 |
callback | コールバックの配信状態 → コールバック |
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 | 冪等。終了済みタスクはそのまま返し、実行中は停止が確認された場合のみキャンセルに成功する |
リモート実行の開始前は、キャンセルによってタスクを停止し、前払い credits を返却します。実行開始後、停止が確認された場合にのみ Beatra は canceled を返します。409 はタスクが継続していることを示します。停止や返金を約束せず、代替タスクを送信せず、同じタスクのポーリングを終端状態まで継続してください。
MiniMax H3 は上流タスクが queued の間だけキャンセルを確認できます。
running に入った後は Beatra が 409 を返し、返金しません。この場合、
確認済みキャンセルを意味しない上流 DELETE は呼び出しません。
明示モデル vs auto
- 明示指定した
modelが黙って置き換えられることはありません。対応しない パラメータがあれば、リクエストは直ちに422 unsupported_optionで失敗し、 フィールド名を示します。 model: "auto"では、具体的なモデルの選択と切り替えはプラットフォームの 設計上の責務です。終端状態のタスクのresolved_modelが実際に実行された モデルを記録します。
生成物の保存
output 内のリソース URL は CDN の URL です。結果を取得したら速やかに自分のストレージへ保存し、永続リンクとして扱わないでください。