Video Motion Cut

Use OpenCVMotionCut to analyze obvious motion and camera-movement highlights in a video. The API returns structured highlight intervals only. Mode selection is not exposed, and no clip files are generated.

Example Video

Create Task

Basic Information

Item	Value
Request Method	POST
Request Path	/task/video_motion_cut
Content-Type	application/json
Authentication	Raw API key in the Authorization header

Request Body

Parameter	Type	Required	Default	Description
file_id	string	Yes	-	Uploaded video file ID

Request Example

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"
  }'

Success Example

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

---

Query Task Result

Basic Information

Item	Value
Request Method	GET
Request Path	/task/video_motion_cut/{task_id}
Authentication	Raw API key in the Authorization header

Output Result (output_result)

Parameter	Type	Description
total_cut_points	integer	Number of detected highlight intervals
video_meta	object	Basic video metadata containing fps, width, and height
cut_points	array<object>	Structured motion-highlight interval list

cut_points Fields

Parameter	Type	Description
id	integer	Interval index
start_frame	integer	Start frame of the interval
end_frame	integer	End frame of the interval
peak_frame	integer	Peak frame of the interval
start_time	number	Start time in seconds
end_time	number	End time in seconds
peak_time	number	Peak timestamp in seconds
duration	number	Interval duration in seconds
direction	number	Main direction of on-screen content motion, computed from atan2(dy, dx) and interpreted in image coordinates; -1 means unavailable
avg_magnitude	number	Average motion magnitude in the interval
peak_magnitude	number	Peak motion magnitude in the interval
consistency	number	Direction consistency. Values closer to 1 mean more stable direction
centroid_x	number	Horizontal centroid of the motion area, normalized to 0-1
centroid_y	number	Vertical centroid of the motion area, normalized to 0-1
coverage	number	Coverage ratio of the obvious motion area
avg_brightness	number	Average brightness of the interval

direction Reference

direction describes the dominant movement direction of the on-screen content, not a direct statement of camera motion itself.

The angle is computed with atan2(dy, dx) from the standard mathematical coordinate system, but interpreted in image coordinates where the y-axis points downward:

                 270° (moving up)
                  ↑
                  |
  180° (moving left) ←---+---→ 0° (moving right)
                  |
                  ↓
                 90° (moving down)

• 0°: on-screen content moves to the right
• 90°: on-screen content moves downward
• 180°: on-screen content moves to the left
• 270°: on-screen content moves upward
• -1: no stable dominant direction can be determined for the interval

This means direction is best read as the visual motion you see in the frame. For example:

• 0° may correspond to a camera panning left, or to a subject moving right
• 180° means the on-screen content moves left overall
• 90° may correspond to an upward camera tilt, or to a subject falling / moving downward
• 270° means the on-screen content moves upward overall

If you use this field to infer camera movement type, remember that camera motion and content motion can be inverse to each other, especially for pan and tilt shots.

Success Example

{
  "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"
  }
}

Error Codes

Error Code	HTTP Status	Description	Resolution
6013	400	Missing file_id	Add the required field
6014	400	File type does not match	Pass a video file ID
6004	404	File not found	Verify the file_id
6502	401	Authentication failed	Check the Authorization header

Usage Limits

• This API currently accepts a single video file per task
• The endpoint is fixed to the OpenCVMotionCut engine and does not expose mode selection
• The API always returns structured results only and never exports clip files