视频机械分镜

基于视频画面变动率检测镜头边界，输出可直接消费的分镜区间。默认仅返回结构化分镜结果；如需拿到切片文件，可将 only_struct 设为 false。

创建任务

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/video_segment`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	—	已上传视频文件的 ID
`detector`	`string`	否	`"content"`	分镜检测器，支持 `content`（画面变动检测）和 `adaptive`（自适应阈值）
`threshold`	`number`	否	`content: 45` / `adaptive: 7.0`	分镜阈值，值越低越敏感；未传时按 `detector` 使用对应默认值
`asi`	`integer`	否	`15`	最短分镜长度，单位为帧
`start_time`	`number`	否	—	分析起始位置；传整数时按帧读取，传浮点数时按秒读取
`end_time`	`number`	否	—	分析结束位置；传整数时按帧读取，传浮点数时按秒读取，且必须大于 `start_time`
`only_struct`	`boolean`	否	`true`	是否仅返回结构化分镜结果，不生成切片文件
`need_audio`	`boolean`	否	`true`	生成切片文件时是否保留音频，仅 `only_struct=false` 时生效

检测器默认阈值

`detector`	默认 `threshold`	说明
`content`	`45`	适合基于画面内容变化做常规分镜
`adaptive`	`7.0`	适合使用自适应阈值做更灵敏的分镜检测

如果没有显式传入 threshold，接口会按上表自动选择默认值。

请求示例

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

成功响应示例

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

查询任务结果

基本信息

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

响应参数（output_result）

参数名	类型	说明
`scene_count`	`integer`	分镜数量
`scene_list`	`array<object>`	分镜区间列表，每项包含 `id`、`start_time`、`end_time`、`duration`
`files`	`array<object>`	切片文件列表，仅 `only_struct=false` 时返回；每项包含 `id`、`file_id`、`download_url`，其中 `id` 对应 `scene_list[].id`

成功响应示例

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

错误码

错误码	HTTP 状态码	说明	解决方案
`6013`	400	缺少 `file_id`	补充必填参数
`6014`	400	文件类型不匹配	传入视频文件 ID
`6016`	400	`detector`、`threshold`、`asi` 或时间区间参数非法	按参数约束重新传值
`6004`	404	文件不存在	检查 `file_id` 是否正确
`6502`	401	鉴权失败	检查 `Authorization` 请求头

使用限制

当前接口仅支持单个视频文件。
start_time 和 end_time 传整数时按帧读取，传浮点数时按秒读取。
当 detector=content 且未传 threshold 时，默认使用 45；当 detector=adaptive 且未传 threshold 时，默认使用 7.0。
end_time 传入时必须大于 start_time。
默认只返回结构化分镜结果；如需导出切片文件，请设置 only_struct=false。