多脸追踪/身份聚类

检测视频中的多张可见人脸，并在一次任务内生成稳定的 person_id、可见时间段和采样轨迹。适用于分屏剪辑、人物出镜统计、自动构图和长视频拆条等只需要视觉人物轨迹、不需要转写或说话人归因的场景。

效果示例

创建任务

基本信息

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

请求参数（Body）

参数名	类型	必填	默认值	说明
`file_id`	`string`	是	-	已上传的视频文件 ID
`time_ranges`	`array`	否	全视频	指定分析时间段，单位毫秒；每项为 `{ "begin_time": 0, "end_time": 30000 }`
`sample_fps`	`number`	否	`5`	分析采样帧率，也控制公开轨迹点密度，范围 `1-10`
`max_faces`	`integer`	否	`5`	每个采样帧最多保留的人脸数量，范围 `1-10`
`min_face_ratio`	`number`	否	`0.001`	最小人脸面积占比，范围 `0.0001-0.05`
`enable_body_match`	`boolean`	否	`false`	是否额外输出匹配的人体框；不需要人体框时建议保持默认
`similarity_threshold`	`number`	否	`0.45`	身份聚类相似度阈值，范围 `0.2-0.9`

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_face_track \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "537489015178246",
    "sample_fps": 3,
    "max_faces": 5,
    "enable_body_match": false
  }'

查询任务

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

output_result 字段

字段	类型	说明
`version`	`string`	输出协议版本，例如 `video_face_track.v1`
`video`	`object`	视频宽高、时长、源帧率、采样帧率、分析帧数和分析时间段
`params`	`object`	本次任务实际使用的公开运行参数
`persons`	`array`	按人物汇总的可见时间段、轨迹片段数、平均置信度、覆盖框和代表框
`tracks`	`array`	按人物返回的采样轨迹点

tracks[].points[] 包含 frame_index、timestamp_ms、face_bbox、face_confidence、face_landmarks、pose、body_bbox 和 interpolated。坐标框均为归一化 [x1, y1, x2, y2]，取值范围 0-1。当姿态角不可靠时，pose.roll、pose.yaw 或 pose.pitch 可能为 null。

完成结果示例

{
  "version": "video_face_track.v1",
  "video": {
    "width": 1920,
    "height": 1080,
    "duration_ms": 18000,
    "source_fps": 25,
    "sample_fps": 3,
    "analyzed_frame_count": 54
  },
  "params": {
    "sample_fps": 3,
    "max_faces": 5,
    "min_face_ratio": 0.001,
    "enable_body_match": false,
    "similarity_threshold": 0.45
  },
  "persons": [
    {
      "person_id": "person_1",
      "first_seen_ms": 0,
      "last_seen_ms": 17500,
      "visible_frame_count": 48,
      "visible_duration_ms": 16000,
      "visible_ranges": [{"begin_time_ms": 0, "end_time_ms": 16000}],
      "face_bbox_union": [0.32, 0.14, 0.58, 0.52],
      "body_bbox_union": null,
      "face_bbox_representative": [0.41, 0.18, 0.53, 0.39],
      "body_bbox_representative": null,
      "avg_face_confidence": 0.94,
      "cluster_confidence": 0.91,
      "track_fragment_count": 2
    }
  ],
  "tracks": [
    {
      "person_id": "person_1",
      "sample_fps": 3,
      "visible_ranges": [{"begin_time_ms": 0, "end_time_ms": 16000}],
      "points": [
        {
          "frame_index": 0,
          "timestamp_ms": 0,
          "face_bbox": [0.41, 0.18, 0.53, 0.39],
          "face_confidence": 0.96,
          "face_landmarks": [[0.44, 0.24], [0.50, 0.24], [0.47, 0.30], [0.45, 0.35], [0.50, 0.35]],
          "pose": {"roll": 0.2, "yaw": -1.6, "pitch": 2.1},
          "body_bbox": null,
          "interpolated": false
        }
      ]
    }
  ]
}

注意事项

person_id 只保证在同一个任务内稳定，不代表跨视频、跨任务或跨账号的真实身份。
sample_fps 和 max_faces 会影响任务耗时和返回 JSON 大小，长视频建议先指定 time_ranges。
enable_body_match=true 会增加额外计算量；只做人脸轨迹时保持默认 false。
*_bbox_union 表示该人物在可见时间内的覆盖范围；用于裁剪或构图时，优先参考 *_bbox_representative。
公开结果不会返回人脸特征向量、逐帧内部表或内部实现细节。