# 動画理解
> 固定サンプリングと秒単位の料金で、上限内の動画 1 本を解析します。

動画理解は、認証済み MCP と REST の両方で利用できるプレビュー機能です。機能と価格は変わることがあります。
上限内の動画 1 本とプロンプトを送信すると、永続的な非同期タスクが返ります。

## MCP

1 回の論理リクエストに対して安定した `client_request_id` を作り、
`beatra.videos.understand` を呼び出します。

```json
{
  "client_request_id": "understand-demo-01",
  "model": "auto",
  "prompt": "出来事の順序と最終結果を要約してください。",
  "video": { "type": "url", "url": "https://example.com/demo.mp4" },
  "detail": "default",
  "response_format": "text"
}
```

現在のモデル、上限、料金を確認するときは、`beatra.models.list` に
`capability: "video_to_text"` を渡します。確定した引数は一度だけ送信し、
返された `task_id` を `beatra.tasks.get` で終端状態までポーリングします。
成功時の回答は `structuredContent.task.output.text` と MCP テキストの両方にあります。

ローカル動画は、正確な MIME タイプとバイト数で `beatra.assets.upload` を呼び、
返された HTTPS `PUT` を生バイトで実行し、レスポンスの `artifact_id` を
`video` 入力として使用します。元素材はアカウントの素材ライブラリに残ります。

## REST

同じ理解フィールドから `client_request_id` を除き、安定した
`Idempotency-Key` ヘッダーとともに `POST /v1/videos/responses` へ送信します。
`GET /v1/tasks/{task_id}` を終端状態までポーリングします。

あなたのアカウントにある `artifact`、外部 HTTPS `url`、base64 `data_uri` を使用できます。
外部・インライン素材は検証後に素材ライブラリへ保存されます。

## 契約と料金

- `prompt` は必須で、空白以外のテキストを含む必要があります。
- 1 回に `video` は 1 本、最大 50 MiB、最大 360 秒です。
- サンプリングは内部で 1 fps 固定です。`fps` やフレーム戦略は公開しません。
- `detail` は `default`、`low`、`high`。既定値は `default` で料金に影響しません。
- `thinking` は非公開で、内部では adaptive thinking を有効にします。
- 現在のモデルは `MiniMax-M3` です。
- 成功時は**受理した入力動画 1 秒あたり 0.4 クレジット**。秒数は切り上げます。
  失敗タスクは課金されません。

入力素材は素材ライブラリに残り、取り込み時のサーバー一時ファイルは処理後に
削除されます。