> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # 视频分析 > 对已上传的 MP4 或 MOV 视频进行带时间戳的多模态分析，可选择 `standard` 或 `deep` 深度。 `POST https://api.beatapi.io/v1/video-analysis/tasks` 对已上传的 MP4 或 MOV 视频进行带时间戳的多模态分析，可选择 `standard` 或 `deep` 深度。 ## 鉴权 `Authorization`   `string`   **必填** 在 `Authorization` 请求头中以 Bearer 令牌发送服务端 API 密钥，可在[控制台](https://beatapi.io/dashboard)创建。 ``` Authorization: Bearer ``` 永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 `Content-Type: application/json`。建议为每个逻辑创建请求设置唯一的 `Idempotency-Key`，只有完全相同的请求体才能安全复用原键。 ## 请求体 字段名、类型和枚举值保留英文原样，用途和限制用中文说明。 本地素材无法通过公网 HTTPS URL 访问时，请先[上传输入文件](/quick-guide#upload-an-input-file)，再使用返回的 `data.url`。 `video_url`   `string`   **必填** 当前账户通过 `POST /v1/files` 上传后得到的 BeatAPI HTTPS 视频 URL。 **取值与默认值:** 格式 `uri` --- `prompt`   `string`   **必填** 描述生成、编辑或分析目标的提示词。 **取值与默认值:** 长度 1–12000 字符 --- `analysis_depth`   `enum`   **选填** 分析深度。`standard` 适合常规摘要和提取，`deep` 适合更密集的动作、接触和连续性推理。 **取值与默认值:** 可选值 `standard`、`deep`；默认值 `standard` --- `max_output_tokens`   `integer`   **选填** 请求的最大输出 Token 预算。 **取值与默认值:** 默认值 `2048`；取值范围 256–8192 ## 响应 成功请求返回 HTTP `201`，响应体如下。 ```json { "data": { "id": "task_va8K2qA", "object": "task", "task_kind": "workflow", "capability_id": "video-analysis", "capability_version": 1, "workflow": "video-analysis", "status": "queued", "stage": "queued", "created_at": 1787385600, "updated_at": 1787385600, "completed_at": null, "output": null, "usage": { "credits_reserved": 0.01, "credits_charged": 0.01, "billable_duration_seconds": 60, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_va123", "error_code": null, "error_message": null } } ``` ## 分析深度与计费 `standard` 是默认方式，适合摘要、分段、时间戳和信息提取。任务需要更密集的动作、接触、连续性或模糊事件推理时，使用 `deep`。 BeatAPI 只接受当前账户通过 `POST /v1/files` 上传的 MP4 或 MOV，最长 600 秒。系统会先按已验证的轨道时长预留费用，完成后再根据已验证的实际输入和输出 Token 用量结算。 普通视频默认约按每秒 1 帧取样。快速动作和密集剪辑可能被遗漏，需要精确动作时建议要求返回时间戳，并使用更短的片段。 ## 下一步 任务完成后从 `data.output.text` 读取分析文本，从 `data.output.usage` 读取 Token 用量。 ## 错误 | 状态码 | 含义与处理方式 | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | JSON 格式错误，或字段、取值、参数组合不被接受（`bad_request`，错误信息会点名字段）；输入未通过内容审核时为 `content_policy_violation`。修正后再请求，原样重试仍会失败。 | | `401` | 未提供 API 密钥（`missing_api_key`），或密钥错误、已过期、已停用或额度已用尽（`invalid_api_key`，错误信息会说明是哪一种）。不要原样重试。 | | `402` | 余额不足（`insufficient_credits`）：账户余额为零或低于本次请求的价格。充值后再请求。 | | `403` | 密钥或账户无权执行该调用（`forbidden`），例如免费额度不能使用该模型（充值即可解锁）、请求来源不在密钥的 IP 白名单内，或模型不在密钥的分组里。不要原样重试。 | | `409` | 幂等键在 24 小时内已用于其他请求体或路径，或使用该键的首个请求仍在处理中（`idempotency_conflict`）。只对完全相同的请求复用原键。 | | `429` | 请求过于频繁（`rate_limit_exceeded`，含免费模型限额）。按 `Retry-After`（也在 `error.retry_after_seconds`）等待后重试。 | | `500` | 内部异常（`internal_error`），可以重试；持续出现时请保留 `request_id` 联系支持。 | | `503` | 请求未能完成（`processing_unavailable`、`processing_timeout`、`processing_failed` 或 `result_transfer_failed`），未扣费，可退避重试；503 不带 `Retry-After` 和 `retry_after_seconds`。BeatAPI 不返回 502 或 504。实时接口在本部署未启用时为 `realtime_disabled`（不可重试），容量暂时不足时为 `realtime_capacity_unavailable`（可重试）。 |