API referenceFaces
Search a collection
Search by a selfie image OR a precomputed 512-d embedding. (POST /v1/collections/{id}/search)
POST
/v1/collections/{id}/search- Auth
- Bearer API key
- Billing
- 93 credits (real-time tier).
Search by a selfie image OR a precomputed 512-d embedding. Returns the matching photo ids ranked by similarity.
Example request
curl -X POST "https://api.sightradar.com/v1/collections/$ID/search" \
-H "Authorization: Bearer $SR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/photo.jpg"}'Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | |
Idempotency-Key | header | string | Opt-in idempotency. A replay under the same key is never re-charged. For a selfie register it returns 200 with the stored result (Idempotent-Replay: true) when the registration identity matches; every other op returns 409. |
Request body (application/json)
| Field | Type | Description |
|---|---|---|
embedding | number[] | |
url | string | |
gcsKey | string | |
threshold | number | Min cosine similarity (0-1). |
limit | integer | Max matches. |
Also accepts: multipart/form-data.
Response body
| Field | Type | Description |
|---|---|---|
collection_id | string | |
matches | object[] | |
photo_ids | string[] | |
reason | string | Present when no match: no_face | low_quality_selfie | point_not_found. |
model_version | string |
Status codes
| Status | Meaning |
|---|---|
200 | Search result. |
400 | Cannot decode image, or no url/gcsKey/body provided. |
401 | Missing or invalid API key. |
402 | Wallet balance too low for this operation. |
409 | A request with this Idempotency-Key is in flight or already processed. |
429 | Per-key RPS or per-customer concurrency limit exceeded. |
502 | Engine error (the credit hold is refunded automatically). |
Last updated
Index faces from a photo
Detects all quality-gated faces in an image and stores them in the collection (Rekognition IndexFaces). (POST /v1/collections/{id}/index)
Search by a stored selfie point id
Search using a previously-registered selfie's pointId (Rekognition SearchFaces by FaceId). (POST /v1/collections/{id}/search-by-id)