Liveness Detection

API Documentation for Liveness Detection

API Version: Version 1 (Latest)

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 112x112 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 restartid 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
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	Returns images generated after post-processing a liveness detection. Note: This field is returned only if the status is "completed".
choices	String	Returns the list of action options generated after post-processing a liveness detection. These actions represent the possible choices that the user may be prompted to perform during the session. Note: This field is only returned if the status is "completed".
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

422: Unprocessable Entity

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

200: OK

{
  // Response
}

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.

422: Unprocessable Entity

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

200: OK

{
  // Response
}

Example code

aiFace Liveness Detection