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)
/v1/collections/{id}/index- Auth
- Bearer API key
- Billing
- 93 credits (real-time tier).
Detects all quality-gated faces in an image and stores them in the
collection (Rekognition IndexFaces). Provide the image as JSON {url} / {gcsKey}, a multipart file, or
raw image bytes. Optional photoId is the per-image key (defaults to a
content hash).
Indexing into a collection_id that does not exist yet creates it. An
index the engine refuses (4xx/5xx) creates nothing and is not charged.
Example request
curl -X POST "https://api.sightradar.com/v1/collections/$ID/index" \
-H "Authorization: Bearer $SR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/photo.jpg"}'Put each id in the path percent-encoded, as a single path segment. An id with /, ?, #, % or a space otherwise addresses a different URL. In code, use your HTTP library's path encoding (for example encodeURIComponent in JavaScript or urllib.parse.quote(id, safe="") in Python).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | |
photoId | query | string | Per-image key (also accepted in body). |
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 |
|---|---|---|
url | string | Public image URL. |
gcsKey | string | Google Cloud Storage object key. |
photoId | string | Optional per-image key. |
Also accepts: multipart/form-data, application/octet-stream.
Response body
| Field | Type | Description |
|---|---|---|
collection_id | string | |
photo_id | string | |
indexed | integer | Faces stored. |
detected_face_count | integer | |
rejected_face_count | integer | Detected but quality-gated out. |
faces | object[] | |
model_version | string |
Status codes
| Status | Meaning |
|---|---|
200 | Faces indexed. |
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 (duplicate_request_*), or, on accounts whose photo_ids are unique across collections, error_code photo_id_in_other_collection: this photoId is already indexed in another collection. Nothing was written and the hold is refunded; error_detail.hint says how to proceed. |
413 | Image exceeds the 30 MB encoded size cap. |
429 | Per-key RPS or per-customer concurrency limit exceeded. |
502 | Engine error (the credit hold is refunded automatically). |