Multi-Face Tracking & Identity Clustering

Detect multiple visible faces in a video and return task-local stable person_id values, visibility ranges, and sampled tracks. Use it for split-screen editing, appearance statistics, auto-cropping, and long-video clipping workflows that need visual person tracks without transcript or speaker attribution.

Example Video

Create Task

Basic Information

Item	Value
Request Method	POST
Request Path	/task/video_face_track
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
time_ranges	array	No	Whole video	Optional analysis ranges in milliseconds, e.g. { "begin_time": 0, "end_time": 30000 }
sample_fps	number	No	5	Sampling rate for analysis and public track density, range 1-10
max_faces	integer	No	5	Maximum faces kept per sampled frame, range 1-10
min_face_ratio	number	No	0.001	Minimum face area ratio, range 0.0001-0.05
enable_body_match	boolean	No	false	Whether to also return matched body boxes; keep it disabled when body boxes are not needed
similarity_threshold	number	No	0.45	Identity clustering similarity threshold, range 0.2-0.9

Request Example

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

Query Task

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

output_result Fields

Field	Type	Description
version	string	Output schema version, for example video_face_track.v1
video	object	Video width, height, duration, source FPS, sample FPS, analyzed frame count, and analyzed ranges
params	object	Public effective runtime options for this task
persons	array	Per-person visibility summary, fragment count, confidence, coverage boxes, and representative boxes
tracks	array	Sampled track points grouped by task-local person

tracks[].points[] contains frame_index, timestamp_ms, face_bbox, face_confidence, face_landmarks, pose, body_bbox, and interpolated. Boxes are normalized [x1, y1, x2, y2] values in the 0-1 range. When pose angles are unreliable, pose.roll, pose.yaw, or pose.pitch may be null.

Completed Result Example

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

Notes

• person_id is stable only within the current task. It is not a cross-video, cross-task, or cross-account identity.
• sample_fps and max_faces affect runtime and JSON size. For long videos, prefer setting time_ranges.
• enable_body_match=true adds extra compute. Keep the default false for face-only tracks.
• *_bbox_union describes the coverage range over visible time. For cropping or composition, prefer *_bbox_representative.
• Public results never return face feature vectors, dense internal frame tables, or internal implementation details.