视频分析

POST https://api.beatapi.io/v1/video-analysis/tasks

对已上传的 MP4 或 MOV 视频进行带时间戳的多模态分析，可选择 standard 或 deep 深度。

鉴权

Authorization   string   必填

在 Authorization 请求头中以 Bearer 令牌发送服务端 API 密钥，可在控制台创建。

Authorization: Bearer <BEATAPI_API_KEY>

永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 Content-Type: application/json。建议为每个逻辑创建请求设置唯一的 Idempotency-Key，只有完全相同的请求体才能安全复用原键。

请求体

字段名、类型和枚举值保留英文原样，用途和限制用中文说明。

本地素材无法通过公网 HTTPS URL 访问时，请先上传输入文件，再使用返回的 data.url。

video_url   string   必填

当前账户通过 POST /v1/files 上传后得到的 BeatAPI HTTPS 视频 URL。

取值与默认值: 格式 uri

prompt   string   必填

描述生成、编辑或分析目标的提示词。

取值与默认值: 长度 1–12000 字符

analysis_depth   enum<string>   选填

分析深度。standard 适合常规摘要和提取，deep 适合更密集的动作、接触和连续性推理。

取值与默认值: 可选值 standard、deep；默认值 standard

max_output_tokens   integer   选填

请求的最大输出 Token 预算。

取值与默认值: 默认值 2048；取值范围 256–8192

响应

成功请求返回 HTTP 201，响应体如下。

1
{
2
  "data": {
3
    "id": "task_va8K2qA",
4
    "object": "task",
5
    "task_kind": "workflow",
6
    "capability_id": "video-analysis",
7
    "capability_version": 1,
8
    "workflow": "video-analysis",
9
    "status": "queued",
10
    "stage": "queued",
11
    "created_at": 1787385600,
12
    "updated_at": 1787385600,
13
    "completed_at": null,
14
    "output": null,
15
    "usage": {
16
      "credits_reserved": 0.01,
17
      "credits_charged": 0.01,
18
      "billable_duration_seconds": 60,
19
      "credits_settled": 0,
20
      "credits_refunded": 0
21
    },
22
    "request_id": "req_va123",
23
    "error_code": null,
24
    "error_message": null
25
  }
26
}

分析深度与计费

standard 是默认方式，适合摘要、分段、时间戳和信息提取。任务需要更密集的动作、接触、连续性或模糊事件推理时，使用 deep。

BeatAPI 只接受当前账户通过 POST /v1/files 上传的 MP4 或 MOV，最长 600 秒。系统会先按已验证的轨道时长预留费用，完成后再根据已验证的实际输入和输出 Token 用量结算。

普通视频默认约按每秒 1 帧取样。快速动作和密集剪辑可能被遗漏，需要精确动作时建议要求返回时间戳，并使用更短的片段。

下一步

任务完成后从 data.output.text 读取分析文本，从 data.output.usage 读取 Token 用量。

错误