Liveness Detection

​Overview

Liveness detection is the process of detecting the presence of a live user, rather than a representation such as a picture or fake video. The user needs to do 3 actions (for more details, please see the following actions table) to pass the liveness test(one round). If the user doesn’t pass the liveness test 3 rounds, the API will respond with the status “uncompleted” which means the billing will also count, else the API will respond with status "processing" or "completed".

Image Requirements

Type : JPG (JPEG), PNG Format : Base64 Size : Must be over 112*112 pixels

How to use liveness detection API

1. Call Get Choices API to get request ID and actions. 2. Call Liveness Detection API with image and request ID, then the liveness detection API will check if the person in the image acts the correct action. You can call Liveness Detection API repeatly until action correct or your time's up. Time limit is up to user but we suggest as 10 second for 1 action. 3. In case that you don't pass the liveness detection until time's up, you can call Liveness Detection API with restart_id parameter True to get new choices. and do the second step again. 4. In case that you pass, you will get 3 images that you just pass the test. You can use these 3 images for other service such as Face Compare.

Request Parameter

Name
Type
Description

Required

request_id

String

Unique ID each session that you can get from Get Choices API

image

String

Base64 encoded binary data of image

restart_id

Boolean

If True, API will return new choices and count as liveness detection fail 1 time. If fail 3 times, this request ID will expired. Note: The default value is False.

Return Values

Fields
Type
Description

request_id

String

Unique ID each session

result

String

Any Liveness result returns when completed an input uploading "Yes" means the action is correct "No" means the action is incorrect Note: if no image uploaded, this string will not be returned

status

String

Process request status showing as either "processing" or "completed", and if it fail 3 times, will show as "incompleted"

images

String

Return images of post-processing a liveness detection Note: if status is completed, this string will be returned

choices

String

Return action options of post-processing a liveness detection Note: if status is completed, this choices will be returned

next_choice

String

Next action from the list. For more details, please see the following actions table

error_message

String

This string will return when request fails. For more details, please see the following error message

time_used

Float

Duration. Unit: second

Actions

Action
Description
Part

Turn_right

Turn right

Face

Turn_left

Turn left

Face

Look_up

Look up

Face

Look_down

Look down

Face

Open_mouth

Open mouth

Face

Smile

smile

Face

Like_right_hand

Thumbs up using your right hand

Hand

Like_left_hand

Thumbs up using your left hand

Hand

I_love_you_right_hand

Show I love you by your right hand

Hand

I_love_you_left_hand

Show I love you by left right hand

Hand

Ok_right_hand

Show Okay sign with your right hand

Hand

Ok_left_hand

Show Okay sign with your left hand

Hand

Handful_right_hand

Show your right fist

Hand

Handful_left_hand

Show your left fist

Hand

One_right_hand

Show one finger with your right hand

Hand

One_left_hand

Show one finger with your left hand

Hand

Two_right_hand

Show two fingers with your right hand

Hand

Two_left_hand

Show two fingers with your left hand

Hand

Three_right_hand

Show three fingers with your right hand

Hand

Three_left_hand

Show three fingers with your left hand

Hand

Four_right_hand

Show four fingers with your right hand

Hand

Four_left_hand

Show four fingers with your left hand

Hand

Forehand_right_hand

Show the front of your right hand

Hand

Forehand_left_hand

Show the front of your left hand

Hand

Backhand_right_hand

Show the back of your right hand

Hand

Backhand_left_hand

Show the back of your left hand

Hand

Victory_right_hand

Show victory sign with your right hand

Hand

Victory_left_hand

Show victory sign with your left hand

Hand

Right_hand

Lift Up your right hand

Hand

Left_hand

Lift Up your left hand

Hand

Error Message

HTTP Status
Error Message
Description

400

IMAGE_ERROR_UNSUPPORTED_FORMAT: <param>

The image which <param> indicates can not be resolved. The file format may not be supported or the file is damaged.

400

MISSING_ARGUMENTS: <key>

Some required arguments missed.

400

BAD_ARGUMENTS: <key>

Error while parsing some arguments. This error may be caused by illegal type or length of argument.

Select Choices

Overview

Get choices data which will be used in the Liveness Detection API.

Request Parameter

Name
Type
Description

Required

mode

Integer Optional

Choose number for livesness actions example 1 - random 1 action Note: The default value is 3

part

String

Choose part "face" and "hand" example choose "face" part will return random actions in face actions example Turn_left, Look_up Note: The default value is None

select

String

Specific choices to random example Turn_left, Turn_right, Left_hand, Backhand_right_hand Note: The default value is None

Return Values

Fields
Type
Description

request_id

String

Unique ID each session

status

String

Process request status showing as "processing"

next_choice

String

Next action from the list

time_used

Float

Duration. Unit: second.

Error Message

HTTP Status
Error Message
Description

400

OVER_ARGUMENTS: <param>

<param> Number more than the limit supported.

400

THE NUMBER OF CHOICES NOT ENOUGH: <key>

List less than actions select.

400

BAD_ARGUMENTS: <key>

Error while parsing some arguments. This error may be caused by illegal type or length of argument.

Get choices data which will be used in the Liveness Detection API.

GET https://apis.aigen.online/aiface/liveness-detection/v1

Query Parameters

Name
Type
Description

mode*

Integer

​Choose number for livesness actions example 1 - random 1 action Note: The default value is 3

part

String

Choose part "face" and "hand" example choose "face" part will return random actions in face actions example Turn_left, Look_up Note: The default value is None

select

String

​Specific choices to random example Turn_left, Turn_right, Left_hand, Backhand_right_hand Note: The default value is None

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Liveness Detection API

POST https://apis.aigen.online/aiface/liveness-detection/v1

Request Body

Name
Type
Description

request_id*

String

Unique ID each session that you can get from Get Choices API

image*

String

Base64 encoded binary data of image

restart_id*

Boolean

If True, API will return new choices and count as liveness detection fail 1 time. If fail 3 times, this request ID will expired. Note: The default value is False.

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Example code

PreviousSelfie Face ComparisonNextaiNLP

Last updated