動画分析

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

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

認証

Authorization   string   必須

BeatAPI の API キーを Bearer トークンとして送信します。API キーはダッシュボードで作成できます。

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 が返されます。

{
  "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 ページと /pricing で確認できます。このページではリクエスト仕様のみを説明しています。

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

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

次の手順

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

エラー