Version 1

POST https://okaylivefacedemo.innov8tif.com/api/check_liveness

Request Body

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

200

{    
    "probability": 0.99,    
    "score": 9.0,    
    "quality": 1.0 
}, 

"Meta" parameter is not required but it can significantly decrease overall error rate. The current version of API supports mobile OS setting.

1KB

OkayLive-AntiSpoofing.postman_collection.json

OkayLive-AntiSpoofing

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.

Interpretation of Result

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

Image Requirements

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.

Face Requirements

• 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.

Capture Requirements

• 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.

Correct Sample

Incorrect Sample

Motion Blur

Spotlight

FACE_TOO_CLOSE

FACE_CLOSE_TO_BORDER

FACE_CROPPED

FACE_NOT_FOUND

FACE_TOO_SMALL

TOO_MANY_FACES

FACE_IS_OCCLUDED

FACE_ANGLE_TOO_LARGE

Capture module

Capturing images and pictures correctly with the mobile device camera is an important element of anti-spoofing detection routine.

Mobile Web

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	github