Logo

视频运镜分析

对视频中的明显动作与运镜进行分析，返回可直接消费的结构化高光区间结果，为快闪类视频的智能剪辑提供辅助。

视频分析示例

创建任务

基本信息

项目值
请求方法POST
请求路径/task/video_motion_cut
Content-Typeapplication/json
鉴权方式Authorization 请求头中直接传 API Key

请求参数

参数名类型必填默认值说明
file_idstring是-已上传视频文件的 ID

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_motion_cut \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246"
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "task_type": "video_motion_cut",
    "status": "queued"
  }
}

查询任务结果

基本信息

项目值
请求方法GET
请求路径/task/video_motion_cut/{task_id}
鉴权方式Authorization 请求头中直接传 API Key

响应参数

参数名类型说明
total_cut_pointsinteger检测到的高光区间数量
video_metaobject视频基础信息，包含 fps、width、height
cut_pointsarray<object>运镜高光区间列表

cut_points 字段说明

参数名类型说明
idinteger区间编号
start_frameinteger区间起始帧
end_frameinteger区间结束帧
peak_frameinteger区间峰值帧
start_timenumber区间开始时间，单位秒
end_timenumber区间结束时间，单位秒
peak_timenumber峰值时间，单位秒
durationnumber区间时长，单位秒
directionnumber画面内容的主运动方向角度；基于 atan2(dy, dx) 计算，并按图像坐标系解释，无法判断时为 -1
avg_magnitudenumber区间平均运动强度
peak_magnitudenumber区间峰值运动强度
consistencynumber方向一致性，越接近 1 越稳定
centroid_xnumber动作区域重心横向位置，归一化到 0-1
centroid_ynumber动作区域重心纵向位置，归一化到 0-1
coveragenumber动作覆盖率，表示明显运动区域占比
avg_brightnessnumber区间平均亮度

direction 方向说明

direction 表示的是画面内容整体朝哪个方向移动，不是“相机本身朝哪个方向运动”的直接表述。

它使用标准数学坐标系中的 atan2(dy, dx) 来计算角度，但要注意视频图像坐标系中 y 轴是向下的，因此解释方式如下：

                 270° (向上运动)
                  ↑
                  |
  180° (向左) ←---+---→ 0° (向右运动)
                  |
                  ↓
                 90° (向下运动)
  • 0°：画面内容整体向右移动
  • 90°：画面内容整体向下移动
  • 180°：画面内容整体向左移动
  • 270°：画面内容整体向上移动
  • -1：当前区间无法稳定判断主方向

这意味着 direction 更适合拿来描述“视觉上看到的运动方向”。例如：

  • 0° 可能表示相机向左平移（left pan），也可能表示主体向右移动
  • 180° 表示画面内容整体向左移动
  • 90° 可能表示相机上摇，也可能表示主体向下运动或下落
  • 270° 表示画面内容整体向上移动

如果你要做“相机运动类型”分析，请注意它和“画面内容方向”在某些情况下是反向关系，尤其是平移、摇镜这类机位运动。

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "total_cut_points": 2,
      "video_meta": {
        "fps": 29.97,
        "width": 1920,
        "height": 1080
      },
      "cut_points": [
        {
          "id": 1,
          "start_frame": 88,
          "end_frame": 136,
          "peak_frame": 112,
          "start_time": 2.9363,
          "end_time": 4.5379,
          "peak_time": 3.7371,
          "duration": 1.6016,
          "direction": 271.4832,
          "avg_magnitude": 3.2947,
          "peak_magnitude": 7.8124,
          "consistency": 0.9132,
          "centroid_x": 0.5148,
          "centroid_y": 0.4372,
          "coverage": 0.2864,
          "avg_brightness": 102.3381
        }
      ]
    },
    "create_time": "2026-04-12T15:40:10Z",
    "update_time": "2026-04-12T15:40:18Z"
  }
}

错误码

错误码HTTP 状态码说明解决方案
6013400缺少 file_id补充必填参数
6014400文件类型不匹配传入视频文件 ID
6004404文件不存在检查 file_id 是否正确
6502401鉴权失败检查 Authorization 请求头

使用限制

  • 当前接口仅支持单个视频文件
  • 接口始终只返回结构化结果，不生成切片文件