Understand video

Video understanding is available through authenticated MCP and REST as a Preview capability. Submit one bounded video and a prompt; Beatra returns a durable asynchronous task.

MCP

Call beatra.videos.understand with one stable client_request_id:

{
  "client_request_id": "understand-demo-01",
  "model": "auto",
  "prompt": "Summarize the sequence of events and the final outcome.",
  "video": { "type": "url", "url": "https://example.com/demo.mp4" },
  "detail": "default",
  "response_format": "text"
}

Use beatra.models.list with capability: "video_to_text" when current model, limit, or price facts matter. Submit the finalized arguments once, then poll the returned task_id with beatra.tasks.get. On success, the answer is in both structuredContent.task.output.text and the MCP text content.

For a local video, call beatra.assets.upload with the exact MIME type and byte length, perform the returned HTTPS PUT with the raw bytes, and pass the returned artifact_id as the video input. The uploaded source remains in the account asset library.

REST

Send the same understanding fields, without client_request_id, to POST /v1/videos/responses and provide a stable Idempotency-Key header. Poll GET /v1/tasks/{task_id} until terminal.

The video may be a tenant-owned artifact, an external HTTPS url, or a base64 data_uri. External and inline inputs are validated, stored in the account's uploaded-material library, and passed to the model from Beatra's CDN.

Contract

• prompt is required and must contain non-whitespace text.
• Exactly one video is accepted.
• The decoded file is limited to 50 MiB and 360 seconds, inclusive.
• Sampling is fixed internally at 1 fps. fps and frame-strategy controls are not public request fields.
• detail accepts default, low, or high, defaults to default, and does not change price.
• thinking is hidden and adaptive thinking is enabled internally.
• MiniMax-M3 is the current selectable model; live discovery remains authoritative.

Billing

Successful requests cost 0.4 credits per admitted input-video second. Duration is rounded up to the next whole second, so 10.001 seconds bills as 11 seconds. Provider token usage does not change the customer charge. Failed tasks are not charged.

Uploaded source material remains available in the account asset library; temporary server files used during ingestion are deleted after processing.