Face Liveness

Passive liveness detection enhances security for person and/or document authentication solutions. It adds detection and alerting capabilities when a printed photo or digital image or a screenshot from monitor/TV is presented for identity authentication or physical access control workflows.

API call

To perform a face liveness check.

This API currently supports basic authentication. All endpoints require an Authentication header in the following form:

Authorization: 'Basic ' + Base64.encode(username + ':' + password)

Send a HTTP POST request to:

  • /api/v1/basic/face/liveness

The following parameters are used for requests and responses:

ParameterDirectionDescription
sessionIdrequestunique, short-lived code to be generated by the client to track specific sessions
faceImageBaserequestonboarded person photo, Base64 format or URL link to it
sessionIdresponseunique, short-lived code to be generated by the client to track specific sessions. Same as in request
scoreresponsescore of the сheck. Higher score means higher liveness level, default threshold is set to 0.5
hasErrorresponseboolean parameter - true - verification process ended up with some error; false - no errors
errorresponseerror message in case of hasError set to true, informing about type of error: FACE_TOO_CLOSE, TOO_MANY_FACES etc.
Request:
{
  "faceImageBase": "data:image/png;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr
...
+SSyDCtmmrGoXzc8AcrURjKEjNOK6DII0ZyJFVgepUdKv26X0WVhuGcMPlBP3RVeFluDiNdvY8VbEUnO2UjaOTnrXoUZc8dTOdSUZEotL7A/eD/AL6oqVLJCoJmk6f3qKv2Rz+0if/Z",
  "sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84"
}

Response - passive liveness passed
{
  "sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
  "passiveLivenessScore": 0.9997104,
  "hasError": false
}

Response - passive liveness not passed:
{
"sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
"passiveLivenessScore": 0.002324,
"hasError": false
}


Response - error
{
  "sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
  "hasError": true,
  "error": "FACE_NOT_FOUND"
}

List of errors

ErrorMeaningDescription
FACE_TOO_CLOSEFace is too close to the cameraA distance between face and image border is too small for preprocessing issues
FACE_CLOSE_TO_BORDERFace is too close to one or more bordersFace is too close to one or more borders. May reduce the accuracy of spoofing detection because edges of face may not be seen
FACE_CROPPEDFace is croppedFace is cropped. May reduce the accuracy of spoofing detection because edges of face may not be seen
FACE_IS_OCCLUDEDFace is occludedThere is occlusion of a face, which impacts the accuracy of liveness. This detection is designed to work with the medical masks that cover nose and mouth, other occlusions are not guaranteed. Occlusion detection has probabilistic nature and may have errors. The threshold setting for occlusion detection may be tuned by changing face_occlusion_threshold setting. Please refer to PAD Configuration in Docker section for more information.
FACE_NOT_FOUNDFailed to detect faceFace detector can’t find face on image. Face detection has probabilistic nature and may have errors. It also has some sensitivity level and very small faces may be ignored.
TOO_MANY_FACESToo many faces detectedFace detector found more than one face on image. Please, note, that very small faces may be ignored if they are below the sensitivity level.
FACE_TOO_SMALLInterpupillary distance / Absolute face size / Relative face size is too smallInterpupillary distance in pixels is below the configured value / The relative proportion of face size in the image is below the configured value / The relative proportion of face size in the image is below the configured value
FACE_ANGLE_TOO_LARGEFacial out-of-plane rotation angle is extremely largeFacial out-of-plane rotation angle is extremely large
internal errors: not listed aboveInternal errorsContact us