> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 動画分析

> アップロード済みの MP4 または MOV を、タイムスタンプを考慮したマルチモーダル推論で分析します。分析の深さは standard または deep を選択できます。

`POST https://api.beatapi.io/v1/video-analysis/tasks`

アップロード済みの MP4 または MOV を、タイムスタンプを考慮したマルチモーダル推論で分析します。分析の深さは standard または deep を選択できます。

## 認証

`Authorization`   `string`   **必須**

BeatAPI の API キーを Bearer トークンとして送信します。API キーは[ダッシュボード](https://beatapi.io/dashboard)で作成できます。

```
Authorization: Bearer <BEATAPI_API_KEY>
```

通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには `Content-Type: application/json` が必要です。対応するエンドポイントでは `Idempotency-Key` は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。

## リクエストボディ

`video_url`   `string`   **必須**

現在のアカウントで POST /v1/files にアップロードして取得した、BeatAPI がホストする MP4 または MOV の入力 URL です。検証した動画の長さの上限は 600 秒です。

**形式:** `uri`

---

`prompt`   `string`   **必須**

分析の指示です。時刻の正確さが重要な場合は、タイムスタンプ付きの出力を要求してください。

**文字数:** 1 – 12000 文字

---

`analysis_depth`   `enum<string>`   **任意**

standard はデフォルトの低コストな処理ルートです。deep は、より高度な推論を行うルートを使用します。

**選択肢:** `standard`, `deep`  \
**デフォルト値:** `"standard"`

---

`max_output_tokens`   `integer`   **任意**

回答に使うトークン数の上限を指定します。サービス側が報告する出力使用量には、この値を超える非表示の推論トークンが含まれる場合があります。BeatAPI は差分を監査用に記録し、タスクの仮確保額の範囲内で、実際に報告された使用量に基づいて精算します。

**デフォルト値:** `2048`  \
**範囲:** 256 – 8192

## レスポンス

リクエストが成功すると、HTTP `201` が返されます。

```json
{
  "data": {
    "id": "task_va8K2qA",
    "object": "task",
    "task_kind": "workflow",
    "capability_id": "video-analysis",
    "capability_version": 1,
    "workflow": "video-analysis",
    "status": "queued",
    "stage": "queued",
    "created_at": 1787385600,
    "updated_at": 1787385600,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.01,
      "credits_charged": 0.01,
      "billable_duration_seconds": 60,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_va123",
    "error_code": null,
    "error_message": null
  }
}
```

## 分析の深さと課金

`standard` は、要約、区間分割、タイムスタンプ、情報抽出に使うデフォルトの処理ルートです。動き、接触、連続性、曖昧な出来事について、より深い推論が必要な場合は `deep` を使用してください。

同じアカウントで `POST /v1/files` にアップロードした、最大 600 秒の MP4 または MOV のみを受け付けます。検証済みのトラック長から入力トークンの使用量を保守的に見積もり、料金を仮確保します。タスク完了後、サービス側から報告された入力・出力トークン数を検証したうえで、その使用量に基づいて精算します。

現在の単価は[動画分析 API ページ](https://www.beatapi.io/video-analysis-api)と `/pricing` で確認できます。このページではリクエスト仕様のみを説明しています。

作成エンドポイントは、リクエストの最大使用量に相当する料金を仮確保してから、キューに入ったタスクを返します。検証済みの実際のトークン使用量を精算する際に、未使用の仮確保額を返還します。共通の米ドル残高はセント単位で精算されるため、完了した各タスクの料金は \$0.01 単位で切り上げられます。

通常の動画は、デフォルトでおよそ毎秒 1 フレームの頻度でサンプリングされます。速い動きや短い間隔でのカット切り替えは見落とされる場合があります。フレーム単位の動きが重要な場合は、タイムスタンプを要求し、短く切り出した動画を使用してください。

## 次の手順

完了した分析結果は `data.output.text`、トークン使用量は `data.output.usage` から取得します。処理枠の空きを待っている場合は、成功または失敗するまで `GET /v1/tasks/{task_id}` をポーリングしてください。

## エラー

| ステータスコード | 意味と対処方法                                                                                                                                                                                                     |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`    | JSON の形式が不正、またはフィールド・値・組み合わせが未対応です（`bad_request`。メッセージにフィールド名が記載されます）。入力がコンテンツ審査で拒否された場合は `content_policy_violation` です。修正せずに再試行しても成功しません。                                                                  |
| `401`    | API キーが未指定（`missing_api_key`）、またはキーが不正・期限切れ・無効・上限到達です（`invalid_api_key`。理由はメッセージに記載されます）。`Authorization: Bearer <key>` で送信してください。`sk-` 接頭辞の有無にかかわらず使えます。そのまま再試行しないでください。                                    |
| `402`    | 残高不足です（`insufficient_credits`）。残高がゼロ、またはこのリクエストの料金に足りません。残高をチャージしてから再度送信してください。それまでは再試行しないでください。                                                                                                            |
| `403`    | キーまたはアカウントに、この呼び出しの権限がありません（`forbidden`）。例として、無料クレジットでは利用できないモデル（チャージすると利用可能）、キーの IP 許可リスト外からのリクエスト、キーのグループに含まれないモデルがあります。そのまま再試行しないでください。                                                                  |
| `409`    | `Idempotency-Key` が別のリクエストボディで使用済み、または同じキーの最初のリクエストが処理中です（`idempotency_conflict`）。そのまま再試行しないでください。                                                                                                          |
| `429`    | リクエスト数が上限を超えています（無料モデルの制限を含む `rate_limit_exceeded`）、または同時処理中のタスクが多すぎます（`user_concurrency_exceeded`）。`Retry-After` の秒数だけ待ってから再試行できます。同じ値は `error.retry_after_seconds` にも含まれます。                               |
| `500`    | 予期しない内部エラーです（`internal_error`）。再試行できます。繰り返し発生する場合は、`request_id` を控えてサポートに連絡してください。                                                                                                                          |
| `503`    | リクエストを完了できませんでした（`processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed`）。課金されていません。待機時間を段階的に延ばして再試行できます。待機時間が判明している場合は `Retry-After` が返されます。BeatAPI は 502 や 504 を返しません。 |