# Understand video
> Analyze one bounded video with fixed sampling and per-second pricing.

Video understanding is available through authenticated MCP and REST as a
preview: the capability and price may change. Submit one bounded video and a prompt; Beatra returns a
durable asynchronous task.

## MCP

Call `beatra.videos.understand` with one stable `client_request_id`:

```json
{
  "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 in your account `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 accepted 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.