Face Detect
Detects face and extracts attributes of it.
API call
To perform face detection and attributes extraction.
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/detect
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 |
| returnFaceImage | request | boolean (true, false) to include/exclude detected face rectangle (Base64 format) in response |
| sessionId | response | unique, short-lived code to be generated by the client to track specific sessions. Same as in request |
| hasError | response | boolean parameter - true - verification process ended up with some error; false - no errors |
| face | response | includes face attributes object |
| face\passiveLivenessScore | response | score of the сheck. Higher score means higher liveness level, default threshold is set to 0.5 |
| face\rectangle | response | includes left, right, top, bottom coordinates of detected face |
| faceImageBase | response | cropped person photo, Base64 format |
| error | response | error message in case of hasError set to true, informing about type of error: INTERNAL_ERROR |
Request:
{
"sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
"faceImageBase": "data:image/png;base64,/9j/4AAQSkZ...AZ4",
"returnFaceImage": true
}
Response - successfull call
{
"sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
"hasError": false,
"face": {
"age": 29,
"gender": -10000,
"passiveLivenessScore": 0.5,
"rectangle": {
"top": 17,
"left": 314,
"width": 422,
"height": 528
},
"faceImageBase": "/9j/4AAQSkZJRgA...RQI//9k="
}
}
Response - error
{
"sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
"hasError": true,
"error": "INTERNAL_ERROR"
}
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_ERROR | Internal errors | Contact us |