Face

Detect Face Liveness

This method helps you to detect liveness from a face image

Recommendation

Only one face exist in the image sent (Holding an identity card is not recommended).
The face in the image must not be blocked by anything, i.e. take off masks
No editing on the image.

prioritize for users to directly capture face image from mobile phone camera
do not compress or crop the image
do not add any elements to the image, i.e. padding

Make sure the image have good quality (avoid blur & dark).
Avoid backlight.
Avoid taking image in a dark environment.

You will receive a response consists of message and an error code if the request fails to process. The following is a list of error codes.

Error Status	Error Code	Description
200	FAIL_ON_2	fail on attribute
200	FAIL_ON_4	fail on quality
200	FAIL_ON_6	fail on attribute and quality
200	FAIL_ON_8	fail on fail on number of face (nface)
200	FAIL_ON_10	fail on fail on number of face (nface) and attribute
200	FAIL_ON_12	fail on fail on number of face (nface) and quality
200	FAIL_ON_14	fail on fail on number of face (nface), quality, and attribute
400	INVALID PAYLOAD	no value in payload or empty string more than 1
400	INVALID_PAYLOAD_IMAGE_MISSING	invalid payload image not a standard b64/url or image empty string
400	INVALID_PAYLOAD_IMAGE_SIZE	invalid payload image size too large
400	MISSING_PAYLOAD_IMAGE	missing payload image
400	INVALID_PAYLOAD_IMAGE_TIMEOUT	timeout getting image from url in 15 seconds
400	INVALID_PAYLOAD_IMAGE_FORMAT	image unable to be decoded/got from url OR invalid image extension
400	FACE_NOT_DETECTED	face not detected from image
400	INVALID_PAYLOAD_QUALITY_VALIDATION_DEPENDENCY	is_quality must be true if validate_quality true
400	INVALID_PAYLOAD_ATTRIBUTE_VALIDATION_DEPENDENCY	is_attribute must be true if validate_attribute true
403	INSUFFICIENT_QUOTA_LIVENESS	usage reach it quota limit for liveness (only appears on testing mode)
500	INTERNAL_SERVER_ERROR	internal server error

post/v1/face/liveness

Request

Base URL
https://api.verihubs.com
URL
https://api.verihubs.com/v1/face/liveness
Auth
none declared. Required headers: App-ID, API-Key

Headers

App-IDstring required

API-Keystring required

Request body

imagestring required

A base64 or URL image file.

is_qualityboolean

A flag to determine whether Image Quality (blur, dark, grayscale) will be computed and return as result

is_attributeboolean

A flag to determine whether Image Attribute (sunglasses, mask, veil, hat) will be detected and return as result

validate_qualityboolean

Determines whether Quality validation will be executed. The validation consists of checking blur and dark with threshold, and also checking whether the image is a black & white image (grayscale is true). It is highly recommended to set validate_quality to true as Liveness is influenced by Quality.

validate_attributeboolean

Determines whether Attribute validation will be executed. The validation consists of checking whether sunglasses or mask is detected in the input image.

validate_nfaceboolean

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

Response

Successful Response

status_codestring

Status Code

messagestring required

Message

session_idstring

unique id to represent transaction record

rotationinteger

Shows how many rotations need to be done to detect face in image

nfaceinteger

Shows how many faces are detected in the input image.

timestampnumber

Shows time which face enrolled successfully

Example response

{
  "status_code": "FACE-2",
  "message": "Face liveness is detected successfully",
  "liveness": {
    "probability": "100"
  },
  "bounding_box": {
    "TopLeftX": "0.9",
    "TopLeftY": "0.9",
    "BottomRightX": "0.9",
    "BottomRightY": "0.9",
    "Width": "0.9",
    "Height": "0.9"
  },
  "face_landmark": {
    "LeftEyeX": "0.9",
    "LeftEyeY": "0.9",
    "RightEyeX": "0.9",
    "RightEyeY": "0.9",
    "NoseX": "0.9",
    "NoseY": "0.9",
    "MouthLeftX": "0.9",
    "MouthLeftY": "0.9",
    "MouthRightX": "0.9",
    "MouthRightY": "0.9"
  },
  "nface": 1
}

Changes

No recorded changes to this operation across all 1 revision of this API.