音视频说话人检测

对视频中的可见人物进行说话人检测，内部自动执行 ASR，并把转写句子、视觉人物轨迹和说话片段融合为结构化结果。适用于访谈、会议、播客、综艺素材等需要知道“谁在什么时候说话”的场景。

效果示例

创建任务

基本信息

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

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	-	已上传的视频文件 ID
`language`	`string`	否	`zh-CN`	内部 ASR 使用的语言代码
`max_faces_per_frame`	`integer`	否	`5`	每个采样帧最多保留的人脸数，范围 `1-10`
`detect_body`	`boolean`	否	`false`	是否额外检测人体框；开启后会使用人体检测模型辅助输出 `body_bbox`
`track_sample_fps`	`number`	否	`5`	每秒最多返回的人物轨迹点数量，范围 `1-30`；实际返回频率会自动不超过视频帧率和内部分析频率

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_speaker_detect \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "language": "zh-CN",
    "max_faces_per_frame": 5,
    "detect_body": true,
    "track_sample_fps": 3
  }'

成功响应示例

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

查询任务

基本信息

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

结果字段

字段	类型	说明
`version`	`string`	输出协议版本，例如 `video_speaker_detect.v1`
`video`	`object`	视频宽高、时长、原始帧率、分析帧率等信息
`params`	`object`	本次任务实际使用的运行参数
`transcript`	`object`	内部 ASR 归一化后的全文、句子和可选词级时间轴
`persons`	`array`	检测到的视觉人物摘要
`speaking_segments`	`array`	视觉说话片段，含时间范围、置信分数和聚合框
`sentence_segments`	`array`	每句话对应的视觉人物归因
`tracks`	`array`	采样后的人物轨迹点，人物移动时会返回随时间变化的 `face_bbox` / `body_bbox`

坐标框均为归一化 [x1, y1, x2, y2]，取值范围 0-1。

完成结果示例

{
  "version": "video_speaker_detect.v1",
  "video": {
    "width": 1920,
    "height": 1080,
    "duration_ms": 18000,
    "source_fps": 25,
    "analysis_fps": 12
  },
  "params": {
    "target_analysis_fps": 25,
    "analysis_fps": 12,
    "max_faces_per_frame": 5,
    "detect_body": true,
    "track_sample_fps": 3
  },
  "persons": [
    {
      "person_id": "person_1",
      "first_seen_ms": 0,
      "last_seen_ms": 17500,
      "visible_frame_count": 120,
      "speaking_duration_ms": 6400,
      "avg_speaking_score": 0.72,
      "max_speaking_score": 0.96
    }
  ],
  "sentence_segments": [
    {
      "sentence_id": "sentence_1",
      "text": "大家好，欢迎来到今天的节目。",
      "begin_time_ms": 500,
      "end_time_ms": 2600,
      "detected_person_id": "person_1",
      "speaker_confidence": 0.88
    }
  ],
  "tracks": [
    {
      "person_id": "person_1",
      "sample_fps": 3,
      "visible_ranges": [{"begin_time_ms": 0, "end_time_ms": 17580}],
      "points": [
        {"timestamp_ms": 0, "face_bbox": [0.41, 0.18, 0.53, 0.39], "body_bbox": [0.36, 0.16, 0.59, 0.82], "is_speaking": true, "speaking_score": 0.91},
        {"timestamp_ms": 333, "face_bbox": [0.42, 0.18, 0.54, 0.39], "body_bbox": [0.37, 0.16, 0.60, 0.82], "is_speaking": true, "speaking_score": 0.89}
      ]
    }
  ]
}

注意事项

detect_body=true 会增加人体检测开销；不需要人体框时建议保持默认 false。
视频自身帧率和内部分析帧率由服务自动读取与决定，调用方不需要传入分析 fps。
track_sample_fps 控制公开结果大小，含义是“每秒最多返回多少个轨迹点”，不影响内部帧级融合精度。
若画面中人物快速移动，tracks[].points 会保留采样后的时间变化框；不要只读取第一帧框。
当视觉证据较弱或多名可见人物难以区分时，sentence_segments[].detected_person_id 可能为 null，或返回较低的 speaker_confidence。
内部 _frame_table 和 frame_details 不会对外返回。