# Compare two faces

> Compare the best face in two images (Rekognition CompareFaces). (POST /v1/compare)

Source: https://sightradar.com/docs/api/faces/compare-two-faces

Compare the best face in two images (Rekognition `CompareFaces`).
Returns cosine similarity (0-1) and a match boolean at the configured
threshold. This is the
ONLY endpoint that can process two photos in one request, and billing is
per photo processed:

* two images (source + target) → **186 credits**
* one image + one precomputed embedding → **93 credits**
* two precomputed embeddings → **93 credits** (one billable operation;
no image is fetched or run through the model)
A side supplied as `source_embedding` / `target_embedding` is not a
processed photo and is not charged as one.

### Example request

```bash
curl -X POST "https://api.sightradar.com/v1/compare" \
  -H "Authorization: Bearer $SR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl":"https://example.com/source.jpg","targetUrl":"https://example.com/target.jpg"}'
```

### Parameters

| Name              | In     | Type     | Description                                                                                                                                                                                                                    |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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 |
| ------------------ | ---------- | ----------- |
| `sourceUrl`        | `string`   |             |
| `sourceGcsKey`     | `string`   |             |
| `targetUrl`        | `string`   |             |
| `targetGcsKey`     | `string`   |             |
| `source_embedding` | `number[]` |             |
| `target_embedding` | `number[]` |             |

### Response body

| Field        | Type          | Description              |
| ------------ | ------------- | ------------------------ |
| `face_found` | `boolean`     |                          |
| `similarity` | `number,null` | Cosine similarity (0-1). |
| `match`      | `boolean`     |                          |
| `threshold`  | `number`      |                          |

### Status codes

| Status | Meaning                                                   |
| ------ | --------------------------------------------------------- |
| `200`  | Comparison result.                                        |
| `400`  | Bad body or missing source/target.                        |
| `401`  | Missing or invalid API key.                               |
| `402`  | Wallet balance too low for this operation.                |
| `429`  | Per-key RPS or per-customer concurrency limit exceeded.   |
| `502`  | Engine error (the credit hold is refunded automatically). |