Guidelines
Start typing to search…

Liveness / Face Anti Spoofing (FAS)

This method helps you detect liveness from face images.

🎈Endpoint

MethodEndpoint
POSThttps://api.verihubs.com/v1/face/liveness

🎈Request

Headers

Key

Type

Notes

Description

App-ID

String

Required

Application ID that generated from Application Menu in Verihubs Client Dashboard. To hit in Testing and Live mode you need a Production Application ID.

API-Key

String

Required

API-Key that generated from Application Menu in Verihubs Client Dashboard that related to specific Application ID.

You can generate your Application ID and API-Key in the Application page in Verihubs Client Dashboard..

Body Parameters

Parameter

Type

Notes

Default

Description

image

String

Required

  • A base64 or URL image file. - Image Type JPEG, JPG, PNG - Max File size: 5MB - Recommended image ratio 4:3 - If the photo is not a face image, it will return “face not detected”.

is_quality

boolean

optional

true

Determines whether Image Quality (blur and dark) will be computed and return as result

is_attribute

boolean

optional

true

Determines whether Image Attribute (sunglasses, mask, veil, hat, and face blocker) will be detected and return as result

validate_quality

boolean

optional

false

Determines whether Quality validation will be executed. The validation consists of checking blur and dark. "validate_quality" can be TRUE only when is_quality is TRUE.

validate_attribute

boolean

optional

false

Determines whether Attribute validation will be executed. The validation consists of checking whether sunglasses, mask, or face blocker is detected in the input image. "validate_attribute" can be TRUE only when "is_attribute" is TRUE.

validate_liveness

boolean

optional

false

Determines whether Liveness validation will be executed. The validation checks whether input image is live / spoof. "validate_liveness" can be TRUE only when "is_liveness" is TRUE.

validate_nface

boolean

optional

false

Determines whether the number of faces validation will be executed. The validation checks whether the input image consists of more than one face.

🎈Responses

Response Code

CodeDescription
200Successful Response
400Bad Request
401Unauthorized
500Internal Server Error

Details for 200 and 201

KeyTypeDescription
messagestringMessage that describe the overall response.
status_codestringStatus that indicate the billing calculation. See status code list in this link.
image_qualityobjectDescribes image quality detail, consist of blur and dark
blurbooleanDescribes whether input image is considered as blur (If it exceeds the threshold, it will detected as blur)
darkbooleanDescribes whether input image is considered as dark (If it exceeds the threshold, it will detected as dark)
attributesobjectDescribes image attributes detail
sunglasses_onbooleanDescribes whether sunglasses is detected on input image
mask_onbooleanDescribes whether mask is detected on input image
veil_onbooleanDescribes whether veil is detected on input image
hat_onbooleanDescribes whether hat is detected on input image
face_blockerbooleanDescribes whether any object is detected blocking the face on input image
livenessobjectDescribes liveness detail
statusbooleanDescribes whether the input image is considered as real or spoof
probabilitystringDescribes the liveness score (0 or 100)
rotationintegerShows rotation degrees need to be done to detect face in image
bounding_boxobjectShows result of bounding box
TopLeftXstring-
TopLeftYstring-
BottomRightXstring-
BottomRightYstring-
Widthstring-
Heightstring-
face_landmarkobjectShows result of face landmark
LeftEyeXstring-
LeftEyeYstring-
RightEyeXstring-
RightEyeYstring-
NoseXstring-
NoseYstring-
MouthLeftXstring-
MouthLeftYstring-
MouthRightXstring-
MouthRightYstring-
nfaceintegerShows how many faces are detected in the input image.
timestampnumberShows time when the process is successfully done

Error Code

Response CodeError MessageDescription
400INVALID_PAYLOADno value in payload or empty string more than 1
400INVALID_PAYLOAD_IMAGE_MISSINGinvalid payload image not a standard b64/url or image empty string
400INVALID_PAYLOAD_IMAGE_SIZEinvalid payload image size too large
400MISSING_PAYLOAD_IMAGEmissing payload image
400INVALID_PAYLOAD_IMAGE_TIMEOUTtimeout getting image from url in 15 seconds
400FACE_NOT_DETECTEDface not detected from image
400INVALID_PAYLOAD_QUALITY_VALIDATION_DEPENDENCYis_quality must be true if validate_quality true
400INVALID_PAYLOAD_ATTRIBUTE_VALIDATION_DEPENDENCYis_attribute must be true if validate_attribute true
400INVALID_PAYLOAD_LIVENESS_VALIDATION_DEPENDENCYis_liveness must be true if validate_liveness true
400INVALID_PAYLOAD_THRESHOLD_MISSINGthreshold choice is incorrect
200FAIL_ON_2fail on attribute
200FAIL_ON_4fail on quality
200FAIL_ON_6fail on attribute and quality
200FAIL_ON_8fail on number of face (nface)
200FAIL_ON_10fail on number of face (nface) and attribute
200FAIL_ON_12fail on number of face (nface) and quality
200FAIL_ON_14fail on number of face (nface), quality, and attribute
403INSUFFICIENT_QUOTA_LIVENESSusage reach it quota limit for liveness (only appears on testing mode)
500INTERNAL_SERVER_ERRORinternal server error

Sample Responses


Response Code

Response

Descriptions

200

        {
            "message": "Face liveness is successful",
            "session_id": "189ea654-a342-4796-9015-dc8b6d84d8d9",
            "status_code": "FACE-14",
            "timestamp": 1675129190.662234,
            "nface": 1,
            "bounding_box": {
                "TopLeftX": "107.69689178466797",
                "TopLeftY": "16.787113189697266",
                "BottomRightX": "144.38543701171875",
                "BottomRightY": "69.24873352050781",
                "Width": "36.68854522705078",
                "Height": "52.46162033081055"
            },
            "face_landmark": {
                "LeftEyeX": "113.55226135253906",
                "LeftEyeY": "37.215999603271484",
                "RightEyeX": "130.2599639892578",
                "RightEyeY": "38.250545501708984",
                "NoseX": "118.09809112548828",
                "NoseY": "46.43742370605469",
                "MouthLeftX": "113.84989166259766",
                "MouthLeftY": "56.04047775268555",
                "MouthRightX": "126.98597717285156",
                "MouthRightY": "56.930213928222656"
            },
            "rotation": 3,
            "image_quality": {
                "blur": false,
                "dark": false,
            }
                "attributes": {
                "sunglasses_on": false,
                "mask_on": false,
                "veil_on": false,
                "hat_on": false,
                "face_blocker": false,
            },
            "liveness": {
                "status": true,
                "probability": "100"
            }
        }

Request data parameter is valid.

400

"message": "Invalid Payload",
"data": {
"message": "Syntax error"
}

Invalid Payload. Transaction that is considered failed due to validation errors, an error_field will appear explaining the error.

400

{
"message": "Face not detected in image",
"error_code": "FACE_NOT_DETECTED"
}

Request image is invalid (not a face image).

401

{
"message": "Authorization failed"
}

Authorization Failed; Transaction that unauthorized due to Application ID or API-Key issue. To hit in Testing and Live mode you need a Production Application ID and API-Key.

403

{
"message": "Insufficient deepfake quota",
"error_code": "INSUFFICIENT_QUOTA_DEEPFAKE"
}

The transaction is in Testing mode and not enough remaining quota. Please contact Verihubs Customer Support.

500

{
"message": "Internal server error"
}

Internal server error.

Response Code

Response

Description

200

{ "message": "Face liveness is successful", "session_id": "189ea654-a342-4796-9015-dc8b6d84d8d9", "status_code": "FACE-14", "timestamp": 1675129190.662234, "nface": 1, "bounding_box": { "TopLeftX": "107.69689178466797", "TopLeftY": "16.787113189697266", "BottomRightX": "144.38543701171875", "BottomRightY": "69.24873352050781", "Width": "36.68854522705078", "Height": "52.46162033081055" }, "face_landmark": { "LeftEyeX": "113.55226135253906", "LeftEyeY": "37.215999603271484", "RightEyeX": "130.2599639892578", "RightEyeY": "38.250545501708984", "NoseX": "118.09809112548828", "NoseY": "46.43742370605469", "MouthLeftX": "113.84989166259766", "MouthLeftY": "56.04047775268555", "MouthRightX": "126.98597717285156", "MouthRightY": "56.930213928222656" }, "rotation": 3, "image_quality": { "blur": false, "dark": false }, "attributes": { "sunglasses_on": false, "mask_on": false, "veil_on": false, "hat_on": false, "face_blocker": false }, "liveness": { "status": true, "probability": "100" } }

Request data parameter is valid

400

{ "message": "Invalid Payload", "data": { "message": "Syntax error" } }

Invalid Payload. Transaction that is considered failed due to validation errors, an error_field will appear explaining the error.

400

{ "message": "Face not detected in image", "error_code": "FACE_NOT_DETECTED" }

Request image is invalid (not a face image).

401

{ "message": "Authorization failed" }

Authorization Failed; Transaction that unauthorized due to Application ID or API-Key issue. To hit in Testing and Live mode you need a Production Application ID and API-Key.

403

{ "message": "Insufficient liveness quota", "error_code": "INSUFFICIENT_QUOTA_LIVENESS" }

The transaction is in Testing mode and not enough remaining quota. Please contact Verihubs Customer Support.

500

{ "message": "Internal server error" }

Internal server error.

Updated about 2 months ago