Video Segment

Detect shot boundaries from visual changes in a video and return structured segment ranges. By default the API returns only structured results. Set only_struct to false if you also want exported clip files.

Create Task

Basic Information

Item	Value
Request Method	POST
Request Path	/task/video_segment
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
detector	string	No	"content"	Segment detector type. Supports content and adaptive
threshold	number	No	content: 45 / adaptive: 7.0	Detection threshold. Lower values are more sensitive. If omitted, the default follows the selected detector
asi	integer	No	15	Minimum segment length in frames
start_time	number	No	-	Optional analysis start position. Integers are interpreted as frame numbers, while floats are interpreted as seconds
end_time	number	No	-	Optional analysis end position. Integers are interpreted as frame numbers, while floats are interpreted as seconds. Must be greater than start_time
only_struct	boolean	No	true	Whether to return only structured segment data without exporting files
need_audio	boolean	No	true	Whether exported clips should keep audio. Applies only when only_struct=false

Detector Default Thresholds

detector	Default threshold	Description
content	45	Recommended for regular cut detection based on visual content changes
adaptive	7.0	Recommended for more sensitive cut detection with adaptive thresholds

If threshold is not provided, the API automatically uses the default value for the selected detector.

Request Example

curl -X POST https://api.ai-mcn.tv:10000/task/video_segment \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "detector": "content",
    "threshold": 45,
    "asi": 15,
    "only_struct": true
  }'

Success Example

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

---

Query Task Result

Basic Information

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

Output Result (output_result)

Parameter	Type	Description
scene_count	integer	Number of detected segments
scene_list	array<object>	Segment ranges. Each item includes id, start_time, end_time, and duration
files	array<object>	Exported clip files, returned only when only_struct=false. Each item includes id, file_id, and download_url, and id maps to scene_list[].id

Success Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "537489015178247",
    "status": "completed",
    "progress": 100,
    "output_result": {
      "scene_count": 2,
      "scene_list": [
        {
          "id": 1,
          "start_time": 0.0,
          "end_time": 6.24,
          "duration": 6.24
        },
        {
          "id": 2,
          "start_time": 6.24,
          "end_time": 12.88,
          "duration": 6.64
        }
      ]
    },
    "create_time": "2026-04-09T08:00:00Z",
    "update_time": "2026-04-09T08:01:05Z"
  }
}

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
6016	400	Invalid detector, threshold, asi, or time range parameters	Adjust the request parameters
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.
• start_time and end_time use frame positions when integers are passed, and second offsets when floats are passed.
• If detector=content and threshold is omitted, the default is 45; if detector=adaptive and threshold is omitted, the default is 7.0.
• When end_time is passed, it must be greater than start_time.
• Structured output is returned by default. Set only_struct=false if you also need clip files.