Core concepts
Collections, faceprints, similarity, the four face operations, and how real-time and batch processing differ.
Collections
A collection is a namespace for faceprints. You choose its id (event-2026-wedding, tenant-42). Searches never cross collections, and deleting a collection is the whole retention story for whatever it contained.
Creating, listing, describing and deleting collections is free. A delete is soft by default: the collection stops accepting index and search immediately, but nothing is erased until a grace window elapses, and POST /v1/collections/{id}/restore undoes it. Pass ?immediate=true (or ?compliance=true for an audited, compliance-class erasure) to skip the grace window. See deleting data.
Faceprints and photos
Indexing a photo runs face detection, drops faces that fail the quality gate (too small, too blurry, too oblique), and stores one faceprint per remaining face: a 512-dimensional L2-normalised embedding. The photo itself is never stored. You keep the image in your own storage and address it by the photoId you supplied at index time (or the content hash SightRadar assigns when you do not).
Each stored face has a point_id. Search results are grouped back to photo_id, because "which photos is this person in" is the question almost every product asks.
Similarity and thresholds
Every match carries a score: cosine similarity between faceprints, from 0 to 1. Higher means more alike. There is no universal cut-off. A wedding gallery can tolerate a looser threshold than a KYC flow, and the right value depends on your photos. Calibrate it from your own labelled pairs and treat any carried-over number (including a Rekognition percentage) as a starting guess. The threshold guide walks through it.
The four operations
| Index | Search | Compare | Detect | |
|---|---|---|---|---|
| Input | one photo | one selfie, or a 512-d embedding | two images, or embeddings | one photo |
| Output | stored faces with point_id and bbox | ranked photo_ids with scores | one similarity and a match boolean | faces with bbox and quality_passed |
| Stores anything? | faceprints only | no | no | no |
| Rekognition equivalent | IndexFaces | SearchFacesByImage | CompareFaces | DetectFaces |
Selfie registration (POST /v1/collections/{id}/selfies) is Index constrained to a single face, keyed by your userId. It returns a point_id you can pass to search-by-id, which skips the model run and is billed at the cheaper search tier. See selfie registration.
Real-time versus batch
Real-time endpoints are synchronous: you get the answer in the HTTP response, and they accept a URL, a Google Cloud Storage key, multipart or raw bytes up to 30 MB.
Batch (POST /v1/batches) takes up to 1,000 URL-only photos per call, processes them asynchronously at the lower batch rate, and delivers one signed webhook per photo. Poll GET /v1/batches/{id}/photos when you want an authoritative pull. See batch and webhooks.
Idempotency
Billable calls are idempotent on request: send an Idempotency-Key header and a retry under the same key is never re-charged and never re-runs the model. A replayed selfie registration returns 200 with the stored point_id and an Idempotent-Replay: true header; every other replayed operation returns 409 before any charge. Without the header, an identical re-run is a new call and is billed again.
Model versions
Responses carry model_version. Faceprints are specific to the model that produced them, which is also why no provider can import another provider's face vectors; migration always means re-indexing from source images.