Liveness Detection
Last updated
Last updated
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".
Type : JPG (JPEG), PNG Format : Base64 Size : Must be over 112*112 pixels
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.
| Name | Type | Description | |
|---|---|---|---|
| Fields | Type | Description |
|---|---|---|
Get choices data which will be used in the Liveness Detection API.
GET https://apis.aigen.online/aiface/liveness-detection/v1
POST https://apis.aigen.online/aiface/liveness-detection/v1
| Action | Description | Part |
|---|---|---|
| HTTP Status | Error Message | Description |
|---|---|---|
| Name | Type | Description | |
|---|---|---|---|
| Fields | Type | Description |
|---|---|---|
| HTTP Status | Error Message | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| 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.
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
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
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.
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
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.
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.
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
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.
