Video Analysis | BeatAPI API Documentation

curl -X POST https://api.beatapi.io/v1/video-analysis/tasks \
     -H "Idempotency-Key: video-analysis-cus_123-01" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "video_url": "https://media.beatapi.io/uploads/input.mp4",
  "prompt": "Return a timestamped action summary and identify every scene transition.",
  "analysis_depth": "standard",
  "max_output_tokens": 2048
}'

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

Analyze an uploaded MP4 or MOV with standard or deep timestamp-aware multimodal reasoning.

If an input is local, upload a local input and use the returned data.url. Save data.id, poll the Task, and follow the error and retry policy.

認証

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

リクエスト

This endpoint expects an object.

video_urlstring必須形式: "uri"

BeatAPI-hosted MP4 or MOV input URL returned by POST /v1/files for the current account. Maximum verified duration is 600 seconds.

promptstring必須1-12000 characters

Analysis instruction. Ask for timestamped output when temporal precision matters.

analysis_depthenumオプションデフォルト値 standard

Standard is the default low-cost route; deep uses the higher-reasoning route.

許可された値:

max_output_tokensintegerオプション256-8192デフォルト値 2048

Requested answer budget. Provider-reported output usage can include hidden reasoning tokens above this value; BeatAPI records the variance for audit and settles actual reported usage within the task reservation.

レスポンス

Analysis accepted for asynchronous processing.

dataobject

Accepted or current BeatAPI task state.

エラー

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error

認証

ヘッダー

リクエスト

レスポンス

エラー