Selfie registration and search-by-id
Register a user's selfie once, get a stable point_id, and run every later search against it at the cheaper tier.
Search-by-image runs the model on every selfie you send. If the same person searches repeatedly (a guest refreshing their gallery, a member checking in each morning), register their selfie once and search by its id instead: no model run, and the search-by-face-id tier at 62 credits instead of 93.
Register the selfie
POST /v1/collections/{id}/selfies is Index constrained to a single face, keyed by your userId. selfieId is optional and defaults to a content hash.
curl -X POST "$SR_BASE/v1/collections/event-2026/selfies" \
-H "Authorization: Bearer $SR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://cdn.example.com/selfies/u_42.jpg", "userId": "u_42"}'{
"face_found": true,
"collection_id": "event-2026",
"user_id": "u_42",
"selfie_id": "9f1c…",
"point_id": "pt_…",
"det_score": 0.93,
"quality_passed": true,
"model_version": "sr-recog-1"
}Store point_id against the user. If face_found is false, reason says why (no_face), and you should ask for another photo.
Search by id
curl -X POST "$SR_BASE/v1/collections/event-2026/search-by-id" \
-H "Authorization: Bearer $SR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pointId": "pt_…", "limit": 50, "threshold": 0.6}'The response is the same SearchResult shape as search-by-image. reason: "point_not_found" means the id does not exist in this collection, for example after the selfie was deleted.
Make registration retry-safe
Registration is billable, and a lost response after a successful charge would leave you without the point_id. Send an Idempotency-Key: a replay of the same registration (same collection, userId, selfieId) returns 200 with the stored identity fields and an Idempotent-Replay: true header, never a second charge. Reusing a key for a different selfie returns 409.
Selfies are scoped to a collection
A point_id lives in one collection. For a user who searches several events, register once per event, or run search-by-image with the stored selfie URL for the rare cross-event case.
Consent
Registering a selfie stores a biometric identifier of a specific, named person. Collect it for the purpose the user expects (finding their own photos), tell them how long you keep it, and delete the collection or the photo when that purpose ends. See trust and responsible use.
Batch indexing and webhooks
Index thousands of photos at the batch rate, receive one signed webhook per photo, verify signatures, and recover from failures.
Choosing a similarity threshold
Turn a 0 to 1 cosine similarity into accept, review and reject decisions using your own data, not a number copied from another vendor.