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.

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

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

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.

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

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.

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.

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

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"
    }
  ]
}

{
    // Response
}