Face Services overview

Face Services is iLive's set of face-recognition primitives: find faces in an image, tell whether two faces are the same person, build a per-tenant collection of reference faces, and search across it at scale. Everything lives under /api/v2/ and is authenticated with a standard API key.

The four pillars

1. Detect

POST /api/v2/faces:detect takes a single image and returns every face it finds, each with a bounding box and optional attributes like pose and quality. Use it to validate uploads before you spend quota on a search, or to power a "we found N faces in your photo" UI.

2. Compare

POST /api/v2/faces:compare takes a source image and a target image and returns a similarity score between 0 and 1. A typical use is matching an ICAO photo from a liveness session against the user's uploaded ID document.

3. Collections

POST /api/v2/collections creates a named bucket scoped to your tenant, and POST /api/v2/collections/{external_id}/faces indexes a face into it. Each indexed face is identified by the iLive-assigned face_id plus your own external_face_id (for example, your user ID).

4. Search

POST /api/v2/collections/{external_id}/search-by-face/{face_id} runs a one-to-many lookup: given a face already in the collection, return the most-similar faces. This is the engine behind duplicate detection and returning-customer recognition.

Typical flows

• Onboarding match. Liveness → ICAO photo → faces:compare against the user's ID. See the KYC onboarding guide.
• Duplicate detection. Index the verified face → search the collection → flag any high-similarity hit with a different external_face_id.
• Returning-customer recognition. A visiting user takes a selfie → you search an existing collection → pick the top hit over a chosen threshold.

Limits to know about

• Max upload size: 8 MB per image. Larger uploads return image_too_large (413). See Error codes.
• Rate limits: per-API-key RPM/RPS. See Rate limits.
• Collections: scoped per tenant, so naming is your choice — use human-readable external_ids like users or staff-photos.

API reference

The auto-generated, always-fresh OpenAPI reference for every Face Services endpoint lives under /docs/api/face-services/*. Start with the detect, compare, collections, and search pages there for exact request and response schemas.

Related: Face attributes · KYC onboarding guide · Error codes.