Skip to main content
POST
Find matching face in video

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Face match request parameters

source_image
object
required

Source image containing the face to search for

target_video_url
string
required

URL of the target video to search in

max_faces
integer

Maximum number of faces to return

Required range: 1 <= x <= 4000
face_detection_id
string<uuid>

Optional: Use previously analyzed face detections in video

frame_extraction_id
string<uuid>

Optional: Use previously extracted frames

frame_extraction_config
object

Optional: Frame extraction configuration

Response

Face match job created successfully

face_match_id
string<uuid>
required

Unique identifier for the face match job

status
enum<string>
required

Status of the face match job

Available options:
pending,
processing,
completed,
failed
created_at
number
required

Unix timestamp in milliseconds when the job was created

face_detection_id
string<uuid>

ID of the face detection analysis used

frame_extraction_id
string<uuid>

ID of the frame extraction used

file_id
string<uuid>

ID of the target file

source_face_bounding_box
object | null

Bounding box of the source face in the source image (null when job is pending/processing)

data
object

Face match results (only present when status is completed)