Version 1
Last updated
Last updated
POST https://okaylivefacedemo.innov8tif.com/api/check_liveness
| Name | Type | Description |
|---|---|---|
apiKey | string | To be assigned by Innov8tif |
data | object | The binary image data uploaded as a file |
Meta | string | The JSON string with device information |
X-Meta | string | The JSON string with any additional information |
"Meta" parameter is not required but it can significantly decrease overall error rate. The current version of API supports mobile OS setting.
Meta Key | Meta Value | Required |
OS | "IOS", "ANDROID" or "UNKNOWN" | True |
MANUFACTURE | "UNKNOWN" | False |
MODEL | "UNKNOWN" | False |
If you're not sure about the device meta, please set 'UNKNOWN' value or just not to pass 'Meta' in the header.
Key | Value |
probability | Probability of liveness |
score | Linear liveness score: bigger value means more alive, (not suggested as a threshold to detect the liveness.) |
quality | Quality value, (not suggested to be used for decision making.) |
error | Error message from the server |
The response of "score" and "quality" is NOT suggested to be used for the decision making for detection result.
Probability of liveness is a main response of the system.
The image is accepted as "live" when a probability is bigger than 0.5.
Linear liveness score can be used for BPCER / APCER tuning. The range of score is (ln 1e-7, -ln 1e-7).
Quality value is a probability of "appropriate image".
Probability can be lower than 0.5 by the reasons below.
Face minimal side is less than 180 pix or distance between eyes is less than 90 pix.
Face out-of-plane rotation is bigger than 20 degrees.
The distance between face and camera is very small, so the face can be significantly distorted.
The luminous power is insufficient.
High motion or gaussian blur rate or light shot.
We highly advise to analyze quality value and reject inappropriate images.
OK response data is always in JSON format. If you received code 200, your data has been accepted, however, there can be one of the following error messages:
Message | Description |
Failed to decode image | Image format is not supported. |
Can't read image from bytes | File is corrupted. |
Failed while detecting face | Face detection module failed during processing of image. |
Failed to detect face | Face detector can't find faces. |
Failed while predict landmarks | Facial landmarks cannot be found. |
Failed to convert image | Internal error. Please send raw data to developers for debugging. |
Failed to predict result | Internal error. Please send raw data to developers for debugging. |
Failed to crop face | Face is too close to camera. |
Face image is too small | Face width or height is under 224 pixels. |
Error message also comes with with error code.
Error | Description |
FACE_TOO_CLOSE | A distance between face and camera is too small for preprocessing issues |
FACE_CLOSE_TO_BORDER | 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. May reduce the accuracy of spoofing detection because edges of face may not be seen |
FACE_IS_OCCLUDED | There is occlusion on the face or it is difficult to see face, which degrades the quality of liveness |
FACE_NOT_FOUND | Face detector can't find face on image |
TOO_MANY_FACES | Face detector found more than one face on image |
FACE_TOO_SMALL | Facial area is not big enough for analysis. Either interpupillary distance(80px) or face size(224 px) is below the configured value. |
FACE_ANGLE_TOO_LARGE | Facial out-of-plane rotation angle is extremely large |
FAILED_TO_PREDICT_LANDMARKS | Landmarks prediction error |
UNKNOWN | Unhandled exception in the code |
Originally, anti-spoofing methods have been developed on smartphone database, which consists of 720p and 1080p horizontally and vertically oriented selfies, taken without any additional post-compressioning. Photo capturing mode result in an increase of True Liveness Rate because it relies less on blur effects.
Recommended height: 720 or 1080.
Minimal supported height: 480.
No image compression is highly recommended: JPEG 70 level as low as practicable.
Minimum image size(width/height): 450px
Vertical Orientation
It’s recommended to use uncompressed formats. If it’s not possible, then it’s recommended to compress image with the highest quality. The difference between near compression levels is invisible to the naked eye but very significant for the anti-spoofing methods retina.
Out-of-plane rotation angle: from -20±3 to 20±3 degrees.
In-plane rotation angle: from -30±3 to 30±3 degrees.
Minimal distance between the eyes of the subject: 80 px.
Minimal face size is 224 pixels in any dimension.
Sun glasses can be confusing.
Motion blur effect can significantly increase BPCER.
Fish-eye lenses are not supported by this API.
Texture filtering can significantly increase APCER.
Spot lights on the faces and nearest surroundings can significantly increase BPCER.
Ill-lighted environment and colored light can significantly increase BPCER.
Rectangular-shaped object in background can significantly increase BPCER.
Capturing images and pictures correctly with the mobile device camera is an important element of anti-spoofing detection routine.
There are two general approaches in Web API to capture a single frame:
Source | Pros | Cons | Compatibility | Sample Code |
File API | Available from any browser | Camera mode control not guaranteed | Low | - |
getUserMedia | Camera mode control | The list of supported browsers is limited | High |
