Face Search

We support both 1:N and N:N face search.

Within a collection, Face Search API allows you to search for previously registered persons using an image with a single that is obtained at a later time. The search is performed using a deep learning model trained on millions of face images. The search results are ranked by the similarity score, which is a number between 0 and 1, where 1 is a perfect match and 0 is a perfect mismatch. The max_results parameter is optional and allows you to control the maximum number of returned results. By default, it is set to 1, but you can customize this number for your specific use case.

If multiple faces are been searched, the search results are returned in order of decreasing similarity score, as long the specified min_score threshold (default is 0.7) is met.

1:N Face Search

POST /face-search

This endpoint is for 1:N search of one face in an image within a collection

Headers

Name	Value
Content-Type	application/json
x-api-key	<your-api-key>

Body

Name	Description
check_liveness	Required: yes Type: boolean Default value: false Accepted values: false, true Example: "check_liveness": false, If set to true, the liveness check is performed during 1:N face search if the face is found. If no face is found, liveness is not checked. Check liveness image requirement here
collection_name	Required: Yes Type: string Example: "collection_name": "MyCollection", Face search is performed within a specified collection. If the person is not enrolled in that collection, the result will be empty.
face_base_64	Required: Yes Type: string Example: "face_base_64": "U2Vjb25kIGltYWdl", Use a Base64-encoded string to perform a 1:N face search. Each image should contain only one face. For N:N face search, use POST /multi-face-search
min_similarity_score	Required: Yes Type: float Default value: 0.7 Example: "min_similarity_score": 0.7 The default value is a good indicator to confirm the match. You can also use a score of 0.67 or higher if the images are of the same person but taken at different times (years apart).
max_results	Required: Yes Type: integer Example: "max_results": 1, The max_results parameter allows you to control the maximum number of returned results. By default, it is set to 1, but you can customize this number for your specific use case.

N:N Face Search

POST /multi-face-search

<This endpoint is for N:N search multiple faces in an image within a collection>

Body

Name	Description
collection_name	Required: Yes Type: string Example: "collection_name": "MyCollection", Face search is performed within a specified collection. If the person is not enrolled in that collection, the result will be empty.
multi_face_img_base_64	Required: Yes Type: string Example: "multi_face_img_base_64": "U2Vjb25kIGltYWdl" This enables searching for multiple faces within an image and retrieving results for all detected faces. If a face is not enrolled in the specified collection, its thumbnail will be returned without a similarity_score.
min_similarity_score	Required: Yes Type: float Default value: 0.7 Example: "min_similarity_score": 0.7 The default value is a good indicator to confirm the match. You can also use a score of 0.67 or higher if the images are of the same person but taken at different times (years apart).

Response

200

1:N Face Search

[
  {
    "face_base_64": "string",
    "metadata": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "person_id": "string",
    "person_name": "string",
    "similarity_score": 0.1
  }
]

N:N Face Search

{
  "person_search_results": [
    {
      "person_id": "string",
      "person_name": "string",
      "metadata": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
      },
      "face_base_64": "string",
      "similarity_score": 0.1
    }
  ],
  "unrecognized_face_thumbnails_base_64": [
    "string"
  ]
}

400

A face could not be detected in the image(s)

{
  "code": "ERR_FACE_NOT_DETECTED",
  "message": "A face could not be detected in the image(s)."
}

401

Please use an API Key to access this endpoint

{
  "code": "ERR_API_KEY_NOT_PRESENT",
  "message": "The API key is missing from the request."
}

403

API Key is invalid. Please provide a valid API Key

{
  "code": "ERR_API_KEY_NOT_VALID",
  "message": "The API key is not valid."
}

404

The collection with the specified name does not exist

{
  "code": "ERR_NOT_FOUND",
  "message": "The requested entity could not be found."
}

412

Liveness error. The metadata contains the code that provides specifics about the error Common codes are: EYES_CLOSED || FACE_CLOSE_TO_BORDER || FACE_CROPPED || FACE_NOT_LIVE || FACE_TOO_CLOSE || FACE_ANGLE_TOO_LARGE || FACE_IS_OCCLUDED || FACE_NOT_FOUND || FACE_TOO_SMALL || LICENSE_ERROR || TOO_MANY_FACES || UNKNOWN_ERROR

{
  "code": "ERR_LIVENESS_ERROR",
  "message": "A liveness error occurred. Please check the supplied image and the error metadata.",
  "metadata": {
    "code": "FACE_NOT_LIVE || .. || UNKNOWN_ERROR"
  }
}

422

The images could not be decoded from base64

{
  "code": "ERR_BASE64_IMAGE_CANNOT_BE_DECODED",
  "message": "The posted Base64 image(s) could not be decoded as JPEG/PNG bytes."
}