Video Analysis

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

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

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

video_url   string   required

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

Format: uri

prompt   string   required

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

Length: 1 to 12000 characters

analysis_depth   enum<string>   optional

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

Available options: standard, deep
Default: "standard"

max_output_tokens   integer   optional

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.

Default: 2048
Range: 256 to 8192

Response

A successful request returns HTTP 201.

1
{
2
  "data": {
3
    "id": "task_va8K2qA",
4
    "object": "task",
5
    "task_kind": "workflow",
6
    "capability_id": "video-analysis",
7
    "capability_version": 1,
8
    "workflow": "video-analysis",
9
    "status": "queued",
10
    "stage": "queued",
11
    "created_at": 1787385600,
12
    "updated_at": 1787385600,
13
    "completed_at": null,
14
    "output": null,
15
    "usage": {
16
      "credits_reserved": 0.01,
17
      "credits_charged": 0.01,
18
      "billable_duration_seconds": 60,
19
      "credits_settled": 0,
20
      "credits_refunded": 0
21
    },
22
    "request_id": "req_va123",
23
    "error_code": null,
24
    "error_message": null
25
  }
26
}

Analysis depth and billing

standard is the default route for summaries, segmentation, timestamps, and extraction. Use deep when the task needs denser reasoning about motion, contact, continuity, or ambiguous events.

BeatAPI accepts only MP4 or MOV inputs of up to 600 seconds uploaded by the same account through POST /v1/files. The verified track duration determines a conservative input-token reservation; the completed task settles from validated provider-reported input and output tokens.

Current unit prices live on the Video Analysis API page and /pricing. This page is the request contract only.

The create endpoint returns a queued task after reserving the maximum request envelope. Any unused reservation is returned when validated actual token usage is settled. Each completed task is rounded up to the nearest $0.01 because the shared USD balance settles in cents.

The model samples ordinary video at roughly 1 FPS by default. Fast actions and dense cuts can be missed, so ask for timestamps and use narrower clips when frame-level motion matters.

Next step

Read completed analysis from data.output.text and token usage from data.output.usage. If the task is queued for capacity, poll GET /v1/tasks/{task_id} until it succeeds or fails.

Errors