---
title: "Detect Face Liveness"
method: POST
path: "/v1/face/liveness"
tags: ["Face"]
---

# Detect Face Liveness

`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`

This method helps you to detect liveness from a face image <br>

Recommendation  <br>
1. Only one face exist in the image sent (Holding an identity card is not recommended).<br>
2. The face in the image must not be blocked by anything, i.e. take off masks <br>
3. No editing on the image. <br>
- prioritize for users to directly capture face image from mobile phone camera <br>
- do not compress or crop the image <br>
- do not add any elements to the image, i.e. padding <br>
4. Make sure the image have good quality (avoid blur & dark). <br>
5. Avoid backlight. <br>
6. Avoid taking image in a dark environment.<br>
  <br> 
  
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.
<br>
  
| 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                                                  |

## Headers

- `App-ID` string, required
- `API-Key` string, required

## Request body

- DetectFaceLiveness
  - `image` string, required: A base64 or URL image file.
  - `is_quality` boolean: A flag to determine whether Image Quality (blur, dark, grayscale) will be computed and return as result
  - `is_attribute` boolean: A flag to determine whether Image Attribute (sunglasses, mask, veil, hat) will be detected and return as result
  - `validate_quality` boolean: 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_attribute` boolean: Determines whether Attribute validation will be executed. The validation consists of checking whether sunglasses or mask is detected in the input image.
  - `validate_nface` boolean: Determines whether the number of faces validation will be executed. The validation checks whether the input image consists of more than one face.

## Response `200`

Successful Response

- ResponseDetectFaceLiveness
  - `status_code` string: Status Code
  - `message` string, required: Message
  - `session_id` string: unique id to represent transaction record
  - `attributes` object
    - `sunglasses_on` boolean
    - `mask_on` boolean
    - `veil_on` boolean
    - `hat_on` boolean
  - `image_quality` object: Shows quality of image
    - `blur` boolean
    - `dark` boolean
    - `grayscale` boolean
  - `liveness` object: Liveness attribute
    - `status` boolean
    - `probability` string
  - `rotation` integer: Shows how many rotations need to be done to detect face in image
  - `bounding_box` object: Shows result of bounding box
    - `TopLeftX` string
    - `TopLeftY` string
    - `BottomRightX` string
    - `BottomRightY` string
    - `Width` string
    - `Height` string
  - `face_landmark` object: Shows result of face landmark
    - `LeftEyeX` string
    - `LeftEyeY` string
    - `RightEyeX` string
    - `RightEyeY` string
    - `NoseX` string
    - `NoseY` string
    - `MouthLeftX` string
    - `MouthLeftY` string
    - `MouthRightX` string
    - `MouthRightY` string
  - `nface` integer: Shows how many faces are detected in the input image.
  - `timestamp` number: Shows time which face enrolled successfully

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `500`: Internal Server Error

---

[API](https://skmtc.dev/verihubs/apis/ai-api-documentation.md) - [All operations](https://skmtc.dev/verihubs/apis/ai-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/verihubs/apis/ai-api-documentation/revisions/9313db607e15?raw)