Compare faces

Score how alike the faces in two images are.

POST /v1/face-similarity/match1 operation per pair

The programmatic form of Compare faces in the dashboard — same models, same allowance.

Request

multipart/form-data, with your key as a bearer token.

Field	Type	Default	Description
image1required	file	—	First image.
image2required	file	—	Second image.
model	string	arcface	Embedding model.
threshold	number	0.75	Match threshold 0–1, reported back so you can compare against it.

Example

curl -X POST https://api.quantilence.com/v1/face-similarity/match \
  -H "Authorization: Bearer $QUANTILENCE_API_KEY" \
  -F "image1=@first.jpg" \
  -F "image2=@second.jpg" \
  -F "model=arcface" \
  -F "threshold=0.75"

Response

200 OK with this shape. Values below are illustrative; the keys and types are not.

{
  "success": true,
  "similarity": [
    {
      "face_1_name": "face_1",
      "face_1_data": "/9j/4AAQSkZJRg…",
      "face_2_name": "face_1",
      "face_2_data": "/9j/4AAQSkZJRg…",
      "sim_score": 87.4
    }
  ],
  "image1_face_count": 1,
  "image2_face_count": 1,
  "image1": {
    "width": 1024,
    "height": 768,
    "faces": [
      {
        "name": "face_1",
        "bbox": [
          412,
          188,
          523,
          361
        ],
        "confidence": 0.93
      }
    ]
  },
  "image2": {
    "width": 800,
    "height": 600,
    "faces": [
      {
        "name": "face_1",
        "bbox": [
          301,
          142,
          409,
          298
        ],
        "confidence": 0.9
      }
    ]
  },
  "model": "arcface",
  "threshold": 0.75,
  "processing_time_ms": 331.2
}

Field	Type	Description
success	boolean	Always true on a 200.
similarity	Pair[]	Every face in image 1 against every face in image 2.
similarity[].face_1_name	string	Label within image 1.
similarity[].face_1_data	string	Base64 crop of that face.
similarity[].face_2_name	string	Label within image 2.
similarity[].face_2_data	string	Base64 crop.
similarity[].sim_score	float	0–100, NOT 0–1. Fifty is the recognition threshold.
image1_face_count	integer	Faces found in image 1.
image2_face_count	integer	Faces found in image 2.
image1	ImageFaces \| null	Frame size and per-face boxes, so a pair can be located on the original.
image2	ImageFaces \| null	The same for image 2.
model	string	Model used.
threshold	float	Threshold applied, 0–1.
processing_time_ms	float	Model time.

Worth knowing

`sim_score` is a percentage 0–100 while `threshold` is 0–1. Compare `sim_score / 100` against it.
Both images may contain several faces; you get every combination, so check the counts before assuming one pair.