# 视频理解
> 分析一个受限视频，固定抽帧并按秒计价。

视频理解是同时通过认证 MCP 与 REST 提供的预览能力，能力和价格可能调整。提交一个受限视频与
提示词后，Beatra 返回可持久追踪的异步任务。

## MCP

调用 `beatra.videos.understand`，并为一次逻辑请求生成稳定的
`client_request_id`：

```json
{
  "client_request_id": "understand-demo-01",
  "model": "auto",
  "prompt": "概括事件发生顺序和最终结果。",
  "video": { "type": "url", "url": "https://example.com/demo.mp4" },
  "detail": "default",
  "response_format": "text"
}
```

需要比较当前模型、限制或价格时，调用 `beatra.models.list` 并传入
`capability: "video_to_text"`。最终参数只提交一次，然后使用
`beatra.tasks.get` 和返回的 `task_id` 轮询到终态。成功后，答案同时位于
`structuredContent.task.output.text` 和 MCP 文本内容中。

对于本地视频，先用准确的 MIME 类型和字节数调用 `beatra.assets.upload`，按
返回信息执行 HTTPS `PUT` 上传原始字节，再把响应中的 `artifact_id` 作为
`video` 输入。上传后的源素材会保留在账号素材库。

## REST

将相同的理解字段（不含 `client_request_id`）提交到
`POST /v1/videos/responses`，并发送稳定的 `Idempotency-Key` 请求头。使用
`GET /v1/tasks/{task_id}` 轮询到终态。

视频可使用你账户里的 `artifact`、外部 HTTPS `url` 或 base64 `data_uri`。
外部和内联素材经过校验后会保存到账号上传素材库，并通过 Beatra CDN 交给模型。

## 契约

- `prompt` 必填，且必须包含非空白文本。
- 一次调用只接受一个 `video`。
- 文件解码后最大 50 MiB，时长不超过 360 秒（含 360 秒）。
- 内部固定按 1 fps 抽帧；不对外暴露 `fps` 或抽帧策略字段。
- `detail` 支持 `default`、`low`、`high`，默认为 `default`，不影响价格。
- 不暴露 `thinking`，内部固定启用 adaptive thinking。
- 当前可选模型为 `MiniMax-M3`，实时模型目录是可用性的最终依据。

## 计费

成功请求按**每个已接受的输入视频秒 0.4 积分**计费，时长向上取整到整秒；
例如 10.001 秒按 11 秒计费。供应商 token 用量不改变客户扣费，失败任务不收费。

输入素材会保留在账号素材库；接收素材时使用的服务器临时文件会在处理结束后删除。