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/face/liveness
The following parameters are used for requests and responses:
| Parameter | Direction | Description |
|---|---|---|
| sessionId | request | unique, short-lived code to be generated by the client to track specific sessions |
| faceImageBase | request | onboarded person photo, Base64 format or URL link to it |
| sessionId | response | unique, short-lived code to be generated by the client to track specific sessions. Same as in request |
| score | response | score of the сheck. Higher score means higher liveness level, default threshold is set to 0.5 |
| hasError | response | boolean parameter - true - verification process ended up with some error; false - no errors |
| error | response | error 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",
"score": 0.9997104,
"hasError": false
}
Response - passive liveness not passed:
{
"sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
"score": 0.002324,
"hasError": false
}
Response - error
{
"sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
"hasError": true,
"error": "FACE_NOT_FOUND"
}
List of errors
| Error | Meaning | Description |
|---|---|---|
| FACE_TOO_CLOSE | Face is too close to the camera | A distance between face and image border is too small for preprocessing issues |
| FACE_CLOSE_TO_BORDER | Face is too close to one or more borders | Face is too close to one or more borders. May reduce the accuracy of spoofing detection because edges of face may not be seen |
| FACE_CROPPED | Face is cropped | Face is cropped. May reduce the accuracy of spoofing detection because edges of face may not be seen |
| FACE_IS_OCCLUDED | Face is occluded | There 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. |
| FACE_NOT_FOUND | Failed to detect face | Face 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_FACES | Too many faces detected | Face 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_SMALL | Interpupillary distance / Absolute face size / Relative face size is too small | Interpupillary 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_LARGE | Facial out-of-plane rotation angle is extremely large | Facial out-of-plane rotation angle is extremely large |
| internal errors: not listed above | Internal errors | Contact us |