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).

身份验证

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

409

Conflict Error

429

Too Many Requests Error

身份验证

请求头

请求

响应

错误