Compare faces on images

Purpose

Use this call to check whether the faces on several images belong to the same person. Each face is compared against every face of every uploaded image.

Request

POST <API_BASE_URL>/face/compare. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.

Content type: multipart/form-data. Send the fields as a multipart form.

Field	Type	Required	Description
`token`	string (uuid)	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`images`	array of file	yes	The image files, 2 to 70 of them.
`multi`	boolean	no	Process every face found. When `false`, only the largest face of each image is processed.
`threshold`	string or number	no	The distance threshold that decides `same_person`.
`feature_check`	array of object or string	no	A feature name or an array of names to detect on each found face, for example `age`, `gender`, `mood`, `glasses`, `mask` or `quality`. The schema lists the full set of names.
`embedding`	boolean	no	Also return the vector representation of each face, base64 encoded. The vector search and fusion operations take this value.
`thumb`	boolean	no	Return a pre-processed crop of each face, base64 encoded.
`bbox`	boolean	no	Return the top-left and bottom-right corners of each face rectangle.

Response

HTTP 200. Comparison finished.

Field	Type	Description
`status`	string	Always `ok` on this body. An upload in which no image carried a face arrives with `status` of `failed`.
`spent`	integer	Processing time in milliseconds.
`results`	array of array of object or string	One entry per uploaded image, in upload order. An image on which no face was found contributes a plain string that says why, in place of the list of faces.
`results[].compare`	array of array of object	This face against every face of every uploaded image, indexed the same way as `results`.
`results[].compare[].same_person`	boolean	Whether the distance between the two faces is within `threshold`.
`results[].compare[].confidence`	string	The similarity as a percentage string, or the string `self` where a face is compared with itself.
`results[].yaw`	number	Head rotation left or right, in degrees.
`results[].pitch`	number	Head tilt up or down, in degrees.

Errors

400: The request failed validation.
401: The token is missing, expired or unknown.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/face/compare" \
  -F "token=<your permanent API token>" \
  -F "images=@first.jpg" \
  -F "images=@second.jpg"

Response:

{
  "status": "ok",
  "spent": 1840,
  "results": [
    [
      {
        "compare": [
          [
            {
              "same_person": true,
              "confidence": "self"
            }
          ],
          [
            {
              "same_person": true,
              "confidence": "97.31%"
            }
          ]
        ],
        "yaw": 4,
        "pitch": -2
      }
    ],
    [
      {
        "compare": [
          [
            {
              "same_person": true,
              "confidence": "97.31%"
            }
          ],
          [
            {
              "same_person": true,
              "confidence": "self"
            }
          ]
        ],
        "yaw": 1,
        "pitch": 0
      }
    ]
  ]
}