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

{    
    "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

PreviousChange LogNextOkayFace - Overall

Last updated

Was this helpful?