---
updatedAt: 2026-08-07T08:07:19.000Z
agentTools:
projectIndex: https://docs.verihubs.com/llms.txt
---
# Detect Face Liveness
This method helps you to detect liveness from a face image
Recommendation
1. Only one face exist in the image sent (Holding an identity card is not recommended).
2. The face in the image must not be blocked by anything, i.e. take off masks
3. 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
4. Make sure the image have good quality (avoid blur & dark).
5. Avoid backlight.
6. 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 |
# OpenAPI definition
```json
{
"openapi": "3.0.2",
"servers": [
{
"url": "https://api.verihubs.com"
}
],
"info": {
"title": "AI API Documentation",
"version": "2.0.0"
},
"tags": [
{
"name": "Face",
"description": "Get information about Face API"
}
],
"paths": {
"/v1/face/liveness": {
"post": {
"tags": [
"Face"
],
"summary": "Detect Face Liveness",
"description": "This method helps you to detect liveness from a face image
\n\nRecommendation
\n1. Only one face exist in the image sent (Holding an identity card is not recommended).
\n2. The face in the image must not be blocked by anything, i.e. take off masks
\n3. No editing on the image.
\n- prioritize for users to directly capture face image from mobile phone camera
\n- do not compress or crop the image
\n- do not add any elements to the image, i.e. padding
\n4. Make sure the image have good quality (avoid blur & dark).
\n5. Avoid backlight.
\n6. Avoid taking image in a dark environment.
\n
\n \nYou 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.\n
\n \n| Error Status |Error Code | Description |\n| ------------------------------------------------|----------------------------------------------------------------------- |----------------------------------------------------------------------- |\n | 200 | FAIL_ON_2 | fail on attribute |\n| 200 | FAIL_ON_4 | fail on quality |\n| 200 | FAIL_ON_6 | fail on attribute and quality |\n| 200 | FAIL_ON_8 | fail on fail on number of face (nface) |\n| 200 | FAIL_ON_10 | fail on fail on number of face (nface) and attribute |\n| 200 | FAIL_ON_12 | fail on fail on number of face (nface) and quality |\n| 200 | FAIL_ON_14 | fail on fail on number of face (nface), quality, and attribute |\n| 400 | INVALID PAYLOAD | no value in payload or empty string more than 1 |\n| 400 | INVALID_PAYLOAD_IMAGE_MISSING | invalid payload image not a standard b64/url or image empty string |\n| 400 | INVALID_PAYLOAD_IMAGE_SIZE | invalid payload image size too large |\n| 400 | MISSING_PAYLOAD_IMAGE | missing payload image |\n| 400 | INVALID_PAYLOAD_IMAGE_TIMEOUT | timeout getting image from url in 15 seconds |\n| 400 | INVALID_PAYLOAD_IMAGE_FORMAT | image unable to be decoded/got from url OR invalid image extension |\n| 400 | FACE_NOT_DETECTED | face not detected from image |\n| 400 | INVALID_PAYLOAD_QUALITY_VALIDATION_DEPENDENCY | is_quality must be true if validate_quality true |\n| 400 | INVALID_PAYLOAD_ATTRIBUTE_VALIDATION_DEPENDENCY | is_attribute must be true if validate_attribute true |\n| 403 | INSUFFICIENT_QUOTA_LIVENESS | usage reach it quota limit for liveness (only appears on testing mode) |\n| 500 | INTERNAL_SERVER_ERROR | internal server error |\n\n\n \n",
"operationId": "detect_face_liveness_post",
"parameters": [
{
"required": true,
"schema": {
"title": "App-ID",
"type": "string"
},
"name": "App-ID",
"in": "header"
},
{
"required": true,
"schema": {
"title": "API-Key",
"type": "string"
},
"name": "API-Key",
"in": "header"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DetectFaceLiveness"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseDetectFaceLiveness"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationError"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationUnauthorized"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ValidationError": {
"title": "ValidationError",
"required": [
"message",
"error_code"
],
"type": "object",
"properties": {
"message": {
"title": "Message",
"type": "string"
},
"error_code": {
"title": "Error_code",
"type": "string"
}
}
},
"ValidationUnauthorized": {
"title": "ValidationUnauthorized",
"required": [
"message"
],
"type": "object",
"properties": {
"message": {
"title": "Message",
"type": "string",
"example": "Authorization failed"
}
}
},
"DetectFaceLiveness": {
"title": "DetectFaceLiveness",
"required": [
"image"
],
"type": "object",
"properties": {
"image": {
"description": "A base64 or URL image file.",
"type": "string"
},
"is_quality": {
"description": "A flag to determine whether Image Quality (blur, dark, grayscale) will be computed and return as result",
"type": "boolean",
"default": true
},
"is_attribute": {
"description": "A flag to determine whether Image Attribute (sunglasses, mask, veil, hat) will be detected and return as result",
"type": "boolean",
"default": true
},
"validate_quality": {
"description": "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.",
"type": "boolean",
"default": false
},
"validate_attribute": {
"description": "Determines whether Attribute validation will be executed. The validation consists of checking whether sunglasses or mask is detected in the input image.",
"type": "boolean",
"default": false
},
"validate_nface": {
"description": "Determines whether the number of faces validation will be executed. The validation checks whether the input image consists of more than one face.",
"type": "boolean",
"default": false
}
}
},
"ResponseDetectFaceLiveness": {
"title": "ResponseDetectFaceLiveness",
"required": [
"message"
],
"type": "object",
"properties": {
"status_code": {
"description": "Status Code",
"type": "string",
"example": "FACE-2"
},
"message": {
"description": "Message",
"type": "string",
"example": "Face liveness is detected successfully"
},
"session_id": {
"description": "unique id to represent transaction record",
"type": "string"
},
"attributes": {
"type": "object",
"properties": {
"sunglasses_on": {
"type": "boolean"
},
"mask_on": {
"type": "boolean"
},
"veil_on": {
"type": "boolean"
},
"hat_on": {
"type": "boolean"
}
}
},
"image_quality": {
"description": "Shows quality of image",
"type": "object",
"properties": {
"blur": {
"type": "boolean"
},
"dark": {
"type": "boolean"
},
"grayscale": {
"type": "boolean"
}
}
},
"liveness": {
"description": "Liveness attribute",
"type": "object",
"properties": {
"status": {
"type": "boolean"
},
"probability": {
"type": "string",
"example": "100"
}
}
},
"rotation": {
"description": "Shows how many rotations need to be done to detect face in image",
"type": "integer"
},
"bounding_box": {
"description": "Shows result of bounding box",
"type": "object",
"properties": {
"TopLeftX": {
"type": "string",
"example": "0.9"
},
"TopLeftY": {
"type": "string",
"example": "0.9"
},
"BottomRightX": {
"type": "string",
"example": "0.9"
},
"BottomRightY": {
"type": "string",
"example": "0.9"
},
"Width": {
"type": "string",
"example": "0.9"
},
"Height": {
"type": "string",
"example": "0.9"
}
}
},
"face_landmark": {
"description": "Shows result of face landmark",
"type": "object",
"properties": {
"LeftEyeX": {
"type": "string",
"example": "0.9"
},
"LeftEyeY": {
"type": "string",
"example": "0.9"
},
"RightEyeX": {
"type": "string",
"example": "0.9"
},
"RightEyeY": {
"type": "string",
"example": "0.9"
},
"NoseX": {
"type": "string",
"example": "0.9"
},
"NoseY": {
"type": "string",
"example": "0.9"
},
"MouthLeftX": {
"type": "string",
"example": "0.9"
},
"MouthLeftY": {
"type": "string",
"example": "0.9"
},
"MouthRightX": {
"type": "string",
"example": "0.9"
},
"MouthRightY": {
"type": "string",
"example": "0.9"
}
}
},
"nface": {
"description": "Shows how many faces are detected in the input image.",
"type": "integer",
"example": 1
},
"timestamp": {
"description": "Shows time which face enrolled successfully",
"type": "number"
}
}
}
}
}
}
```