NAV Navbar
Logo

3D Liveness Detection

Introduction

ADVANCE AI offers Liveness Detection technology that verifies an online user is a real person.

The latest version is 3D Liveness Detection, the user is asked to move far away and close to camera so as to complete the Liveness Detection Process.

Click here If you need 2D Liveness Detection.

There are 4 steps to integrate the Liveness Detection Service.

Note: Generated “livenessId” successfully as the billing tag

Liveness Detection License Authorization

Code Sample

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{"licenseEffectiveSeconds": 600,"applicationId": "appId1,appId2" }' \
"https://api.advance.ai/openapi/liveness/v1/auth-license"

Request Url

https://api.advance.ai/openapi/liveness/v1/auth-license
POST (application/json)

Request Header Parameters:

Parameter Description
X-ACCESS-TOKEN string Please Click here to get your access token

Request Parameters:

Parameter Description
licenseEffectiveSeconds int optional The license effective period, defaults to 600 seconds, maximum 86400 seconds. Unit is seconds
applicationId string optional The list of valid applicationId

URL Example of Success Response:

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data":{
        "license":"jpgEkQQFKD+EXHBmIFLOycYOMkohFVyJzhfq5M0F95pp3EDcLf8Z31e4xqyeyhNXfW......",
        "expireTimestamp": 1603164618149
    },
    "extra":null
}

Example of Access Denied Response:

{
     "code": "ACCESS_DENIED",
     "message": "Access denied",
     "transactionId": "eb0c771967789e58",
     "data": null,
     "extra": null,
     "pricingStrategy": "FREE"
}

Example of Service Disabled Response:

{
     "code": "SERVICE_DISABLED",
     "message": "Service disabled",
     "transactionId": "789196eb0c777e58",
     "data": null,
     "extra": null,
     "pricingStrategy": "FREE"
}

Response Description:

Parameter Description
code Liveness Detection License Authorization Status Code
transactionId The request id, the max length is 64
pricingStrategy Whether the request will be charged, enum type: FREE, PAY
message Status Code Explanation
data license : Authorization code within validity period
expireTimestamp : Expiration timestamp
extra Extra response info (Exception Message)

Response Code

Status Code Message
ACCESS_DENIED free Access denied
SERVICE_DISABLED free Service disabled

Note: Don’t Forget to add handler for these Status Codes in Glossary as well

SDK Integration Guide

Android

iOS

Liveness Detection

Note : Please first check the Glossary for basic information about ADVANCE API.

Code Sample

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{"livenessId": "ddsd-9e6-dcc9-4ca1-bdfe-9f001c05f1b1","resultType": "IMAGE_URL"}' \
"https://api.advance.ai/openapi/liveness/v3/detection-result"

IMPORTANT

Before using this service, please note the following:

Request URL

https://api.advance.ai/openapi/liveness/v3/detection-result
POST (application/json)

Request Header Parameters:

Parameter Description
X-ACCESS-TOKEN string Please Click here to get your access token

Request Parameters:

Parameter Description
livenessId string an identifier for your user’s face photo from the SDK
resultType string optional the preferred format for the liveness image, IMAGE_URL or IMAGE_BASE64. The default will be IMAGE_URL

Notes:

URL Example of Success Response:

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data": {
        "detectionResult":"https://XXXX/standard-images/random_20180929195400851_1478837456",
        "livenessScore": 100.0,
        "auditImageUrl": "https://XXXX/standard-images/random_20180929195400851_1478837456",
        "imageFarUrl": "https://",
        "farImageTime": 1713247589908,
        "imageNearUrl": "https://",
        "nearImageTime": 1713247589908,
        "attackType": null,
        "attackSubType": null
    },
    "extra":null
}

Image Base64 Example of Success Response:

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data":{
        "detectionResult":"/9j/4AAQSkZJRgABAQAAAQABAAD/...",
        "livenessScore": 100.0,
        "auditImageUrl": "https://XXXX/standard-images/random_20180929195400851_1478837456",
        "imageFarUrl": "https://",
        "farImageTime": 1713247589908,
        "imageNearUrl": "https://",
        "nearImageTime": 1713247589908,
        "attackType": null,
        "attackSubType": null
    },
    "extra":null
}

auditImageUrl is null Example of Success Response:

{
    "code":"SUCCESS",
    "transactionId": "196eb0c777789e58",
    "pricingStrategy": "PAY",
    "message":"OK",
    "data": {
        "detectionResult":"https://XXXX/standard-images/random_20180929195400851_1478837456",
        "livenessScore": 100.0,
        "auditImageUrl": null,
        "imageFarUrl": "https://",
        "farImageTime": 1713247589908,
        "imageNearUrl": "https://",
        "nearImageTime": 1713247589908,
        "attackType": null,
        "attackSubType": null
    },
    "extra":null
}

Example of Success Response When livenessScore=0:

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "detectionResult": "https://",
        "livenessScore": 0.0,
        "auditImageUrl": null,
        "imageFarUrl": "https://",
        "imageNearUrl": "https://",
        "nearImageTime": null,
        "farImageTime": null,
        "attackType": 3,
        "attackSubType": null
    },
    "extra": null,
    "transactionId": "16733ebf2ca75a0b",
    "pricingStrategy": "PAY"
}

Example of Failed Request / Error Response:

{
  "message": "Liveness id does not exist",
  "data": null,
  "extra": null,
  "code": "LIVENESS_ID_NOT_EXISTED",
  "transactionId": "196eb0c777789e58",
  "pricingStrategy": "FREE"
}

Example of RESULT_NOT_FOUND Response:

{
    "code":"RESULT_NOT_FOUND",
    "message":"The requested resource was not found or has been deleted",
    "data":null,
    "extra":null,
    "transactionId":"d5bec4f642549caf",
    "pricingStrategy":"FREE"
}

Response Description:

Parameter Description
code Liveness Detection Status Code
transactionId The request id, the max length is 64
pricingStrategy Whether the request will be charged, enum type: FREE, PAY
message Status Code Explanation
data detectionResult : string The image URL or the image base64
livenessScore : double The score for anti-spoofing, ranging from [0,100], less than 50 means it might be an attack. Please refer to the Note below of given suggestions based on different liveness scores.
auditImageUrl : string The audit image link
imageFarUrl : string Photo taken by user in far stage
imageNearUrl : string Photo taken by user in near stage
farImageTime : long Timestamp of the imageFar
nearImageTime : long Timestamp of the imageNear
attackType : int Return attacktype when livenessScore=0
1 Presentation Attack
2 Injection Attack
3 Unsure Attack
attackSubType : Currently return null, will return more details in the future
extra Extra response info (Exception Message)

Note:

Note:

Response Code

Status Code Message
LIVENESS_ID_NOT_EXISTED free Liveness Id does not exist
RESULT_NOT_FOUND free The requested resource was not found or has been deleted
PARAMETER_ERROR free Parameter error, please check your request whether has illegal parameters

Note: Please remember to add a handler for the Status Codes in the Glossary as well

PII Data Retention

Note : Please first check the Glossary for basic information about ADVANCE API.

Code Sample

curl -X GET \
-H "X-ACCESS-TOKEN: {Your Access Token}" \

"https://api.advance.ai/liveness/ext/v1/clear-data?livenessId=ddsd-9e6-dcc9-4ca1-bdfe-9f001c05f1b1"

Request URL

https://api.advance.ai/liveness/ext/v1/clear-data
GET

Request Header Parameters:

Parameter Description
X-ACCESS-TOKEN string Please Click here to get your access token

Request Parameters:

Parameter Description
livenessId string The livenessid which you want to clean up

Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":null,
    "extra":null,
    "transactionId":"ac66706068e737b5",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter error, please check your request whether has illegal parameters",
    "data":null,
    "extra":null,
    "transactionId":"a2190c8682344303",
    "pricingStrategy":"FREE"
}

Example of ERROR Response:

{
    "code":"ERROR",
    "message":"server error",
    "data":null,
    "extra":null,
    "transactionId":"90bd3e1bd2acea48",
    "pricingStrategy":"FREE"
}

Response Description:

Parameter Description
code Liveness Detection Status Code
transactionId The request id, the max length is 64
pricingStrategy Whether the request will be charged, enum type: FREE, PAY
message Status Code Explanation
data null
extra Extra response info (Exception Message)

Response Code

Note: Please remember to add a handler for the Status Codes in the Glossary as well

Token Authentication

Request Parameters:

Parameter Description
accessKey string the accessKey
timestamp string 13-digit-long timestamp, suggested 300 seconds before or after the current time when requesting the token
signature string Combined accessKey, secretKey and timestamp, encrypted by SHA256.
eg.
accessKey: sampleaccesskey
secretKey: samplesecretkey
timestamp: 1665993522952
Combined: sampleaccesskeysamplesecretkey1665993522952
Encrypted based on the combined: 02209bbeaf0d0a3dd587f6a1ba22f84c98d142e3b545e77db7e4906ca56349f5
periodSecond string optional Validity period defaults to 3600 seconds, minimum 60 seconds, maximum 86400 seconds. Unit is seconds

Note:

Code Sample

curl -X POST \
-H "Content-Type: application/json" \
-d '{"accessKey":"22********70b","signature":"f786441e7b3d95f*****************853a5a244f9522","timestamp":1648785145789,"periodSecond":120}' \ 
"https://api.advance.ai/openapi/auth/ticket/v1/generate-token"

Request Url

https://api.advance.ai/openapi/auth/ticket/v1/generate-token
POST (application/json)

Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJoNV9saXZlbmVzcyIsInN1YiI6IntcImN1c3RvbWVySWRcIjo1NTAwMDI4MixcImFjY291bnRJZFwiOjU1MDAwMjg0LFwicmVhbElwXCI6XCI0NS4yNTEuMTA3LjExMVwifSIsImF1ZCI6IldFQiIsImlhdCI6MTY0MjU4MDA3MiwiZXhwIjoxNjQyNTgwMTkyfQ.HmIDcuSW67A59x7bnumjGp0Wdcz-FmoDrnHF1YGui6wVPfulLn4Izonay5LQnySgph1dbyC1E0LtifS-BJo8VA",
    "expiredTime":1642580192430
    },
    "extra":null,
    "transactionId":"6c2c50a3049ce67e",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"040e769e38f87e3e",
    "pricingStrategy":"FREE"
 }


{
    "code":"PARAMETER_ERROR",
    "message":"Timestamp error",
    "data":null,
    "extra":null,
    "transactionId":"a9c2a6c199ad5db5",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Signature error",
    "data":null,
    "extra":null,
    "transactionId":"00b05cb9cf6f0fed",
    "pricingStrategy":"FREE"
}

Example of ACCOUNT_DISABLED Response:

{
    "code":"ACCOUNT_DISABLED",
    "message":"Account Disabled",
    "data":null,
    "extra":null,
    "transactionId":"5e00fded1272490e",
    "pricingStrategy":"FREE"
}

Example of CLIENT_ERROR Response:

{
    "code":"CLIENT_ERROR",
    "message":"HTTP 400 - Bad Request",
    "data":null,
    "extra":null,
    "transactionId":"bd5d5653c45d4c6e",
    "pricingStrategy":"FREE"
 }

Response Description:

Parameter Description
code Response Status Code
message Message returned from server
data token AccessToken
expiredTime Expiration timestamp
extra Extra response info such as exception message
transactionId the request id, the max length is 64
pricingStrategy whether the request will be charged, enum type: FREE, PAY

Response Code

Status Code Message
SUCCESS free OK
PARAMETER_ERROR free Parameter should not be empty
free Timestamp error
free Signature error
ACCOUNT_DISABLED free Account Disabled
CLIENT_ERROR free HTTP 400 - Bad Request

Glossary

Welcome to the Glossary!

Please read the following to understand how ADVANCE API system, for a smooth integration. We will explain all the basics you need to know about our API.

Status Code

Notes:

Status Code Message
SUCCESS pay OK
ERROR free Server error
EMPTY_PARAMETER_ERROR free Parameter should not be empty
INSUFFICIENT_BALANCE free Insufficient balance, please top up or contact your sales manager for help
SERVICE_BUSY free Messages may look like:
Rate limit is exceeded, please retry after the suggested time in HTTP Header.
Retry-After :10s
p.s. Please also note that this code may migrate to HTTP 429 Too Many Requests in the future.

Quota exceeded: You have exceeded the daily quota for free queries, please contact out tech support for help
IAM_FAILED free Access denied. Messages may look like:
You are not authorized by the Identity and Access Management system
Access Key not found
Token not found or expired
Access Key not found or expired
Account not authorized for this country
Account not authorized for this domain
Account is expired. Please contact your sales manager for help
Account is disabled. Please contact your sales manager for help
Access denied: Token not found or expired
PARAMETER_ERROR free The message is detailed error description, may includes:
Parameter should not be empty
Invalid phone number, please check your phone number format
etc.
p.s. Mobile number format should be country code + phone number(without leading 0 or dash or space e.g. +xx12345678); fixed-line number should be country code + area code + number(without leading 0)
OVER_QUERY_LIMIT free Messages may look like:
Quota exceeded. you have exceeded free query quota, please contact your sales manager for help
Quota exceeded: You have exceeded free query quota for test account, please contact your sales manager for help
CLIENT_ERROR free HTTP client error. Messages may look like:
HTTP 400 - Bad Request
HTTP 404 - Not Found
HTTP 405 - Method Not Allowed
etc.
If you get this error, please check the API document or contact our tech support for help.
RETRY_LATER free Query failed, please retry after the suggested time in HTTP Header.
Retry-After :10s

Notes:

Request URL & Parameters

Parameter Description
requestString string String value for API request
requestFile file Request file for API request
requestInteger optional integer Number value for API request

Response

Parameter Description
code API Status Code
message Status Code Explanation
data field1: explanation of the first information that will be returned from ADVANCE
field2: explanation of the second information that will be returned from ADVANCE
extra Extra response info (Exception Message)

Image Quality Requirements