VideoFacesConverter
Detect, track, and extract all faces appearing in a video. Returns aligned face crops, bounding boxes, timestamps, and optional identity embeddings for each detected face. Supports face clustering to group appearances of the same person across the video.
How It Works
Upload a video file or provide a URL to the Mixpeek API.
Frames are sampled and processed through a face detection model (SCRFD) to locate faces.
Detected faces are tracked across frames to maintain identity continuity.
Each unique face is aligned and cropped using facial landmark detection.
Face identity embeddings (ArcFace 512D) are generated for each unique face, enabling clustering and matching.
Code Examples
import os, requests
API = "https://api.mixpeek.com"
H = {"Authorization": f"Bearer {os.environ['MIXPEEK_API_KEY']}",
"X-Namespace": os.environ["NAMESPACE_ID"]}
# 1. a bucket, with a schema that declares the field you will send
bucket = requests.post(f"{API}/v1/buckets", headers=H, json={
"bucket_name": "video-inputs",
"bucket_schema": {"properties": {"video": {"type": "video"}}},
}).json()
# 2. land the file as an object. the URL goes in data, on the blob
requests.post(f"{API}/v1/buckets/{bucket['bucket_id']}/objects", headers=H, json={
"key_prefix": "run-1",
"blobs": [{"property": "video", "type": "video",
"data": "https://example.com/clip.mp4"}],
})
# 3. a collection over that bucket, running the extractor
collection = requests.post(f"{API}/v1/collections", headers=H, json={
"collection_name": "video-to-faces",
"source": {"type": "bucket", "bucket_ids": [bucket["bucket_id"]]},
"feature_extractor": {"feature_extractor_name": "multimodal_extractor", "version": "v1"},
}).json()
# 4. run extraction over the bucket
requests.post(f"{API}/v1/buckets/{bucket['bucket_id']}/batches", headers=H, json={
"collection_ids": [collection["collection_id"]],
"auto_submit": True,
})
# 5. read the output
docs = requests.get(
f"{API}/v1/collections/{collection['collection_id']}/documents", headers=H
).json()
print(docs)Use Cases
Supported Input Formats
Quick Info
Run it over a library
Mixpeek runs this conversion as a pipeline over a whole library in your object storage, with the output landing as queryable documents. It is not a single-file converter.
Frequently Asked Questions
Related Converters
Video to Keyframes
Automatically detect scene changes and extract representative keyframes from any video. Each keyframe includes a timestamp, scene label, and optional caption generated by a vision model.
Video to Thumbnails
Generate optimized thumbnail images from video files. Uses intelligent frame selection to pick the most visually appealing and representative frames, with optional face detection and composition scoring.
Video to Scenes
Automatically segment videos into individual scenes using visual and audio cue detection. Each scene includes a start and end timestamp, a representative keyframe, a descriptive label, and a confidence score for the detected boundary.
Video to Metadata
Extract comprehensive technical and semantic metadata from video files. Returns codec details, resolution, duration, frame rate, and AI-generated semantic tags including detected objects, scenes, dominant colors, and content categories.
Image to Metadata
Extract comprehensive technical and semantic metadata from images. Returns EXIF data, camera settings, GPS coordinates, and AI-generated semantic tags including detected objects, scene type, dominant colors, and content categories.
Ready to convert video to faces?
Start using the Mixpeek Video to Faces in minutes. Sign up for a free API key and follow the documentation to get started.