视频理解

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

MCP

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

{
  "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 credits计费，时长向上取整到整秒； 例如 10.001 秒按 11 秒计费。供应商 token 用量不改变客户扣费，失败任务不收费。

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