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.

Analyze an uploaded MP4 or MOV with standard or deep timestamp-aware multimodal reasoning. If an input is local, [upload a local input](/quick-guide#upload-an-input-file) and use the returned `data.url`. Save `data.id`, [poll the Task](/quick-guide#get-task-status), and follow the [error and retry policy](/quick-guide#errors-and-retry-policy).

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.

video_urlstringRequiredformat: "uri"

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

promptstringRequired1-12000 characters

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

analysis_depthenumOptionalDefaults to standard

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

max_output_tokensintegerOptional256-8192Defaults to 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.

Response

Analysis accepted for asynchronous processing.

dataobject

Accepted or current BeatAPI task state.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

409

Conflict Error

429

Too Many Requests Error

Authentication

Headers

Request

Response

Errors