LivenessCompare

Last updated: 2020-12-09 15:18:18

1. API Description

Domain name for API request: faceid.tencentcloudapi.com.

This API is used to pass in a video and a photo, determine whether the person in the video is real, and if yes, then determine whether the person in the video is the same as that in the photo.

A maximum of 20 requests can be initiated per second for this API.

Note: This API supports Finance regions. If the common parameter Region is a Finance region, a domain name with the Finance region needs to be specified, for example: faceid.ap-shanghai-fsi.tencentcloudapi.com

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common parameter. The value used for this API: LivenessCompare.
Version Yes String Common parameter. The value used for this API: 2018-03-01.
Region Yes String Common parameter. For more information, please see the list of regions supported by the product.
ImageBase64 Yes String Base64 string of the image for face comparison.
The size of the Base64-encoded image data can be up to 3 MB. JPG and PNG formats are supported.
Please use the standard Base64 encoding scheme (with the "=" padding). For the encoding conventions, please see RFC 4648.
VideoBase64 Yes String Base64 string of the video for liveness detection.
The size of the Base64-encoded video data can be up to 8 MB. MP4, AVI, and FLV formats are supported.
Please use the standard Base64 encoding scheme (with the "=" padding). For the encoding conventions, please see RFC 4648.
LivenessType Yes String Liveness detection type. Valid values: LIP/ACTION/SILENT.
LIP: numeric mode; ACTION: motion mode; SILENT: silent mode. You need to select a mode to input.
ValidateData No String Input parameter for the numeric mode: numeric verification code (1234). An API needs to be called first to get a numeric verification code;
Input parameter for the motion mode: motion order (2,1 or 1,2). An API needs to be called first to get the motion order;
Input parameter for silent mode: empty.
Optional No String This parameter does not need to be passed in for this API.

3. Output Parameters

Parameter Name Type Description
BestFrameBase64 String The best screenshot of the video after successful verification. The photo is Base64-encoded and in JPG format.
Sim Float Similarity. Value range: [0.00, 100.00]. As a recommendation, when the similarity is greater than or equal to 70, it can be determined that the two faces are of the same person. You can adjust the threshold according to your specific scenario (the FAR at the threshold of 70 is 0.1%, and FAR at the threshold of 80 is 0.01%).
Result String Service error code. Success will be returned for success. For error information, please see the FailedOperation section in the error code list below.
Description String Service result description.
BestFrameList Array of String
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Detecting silent liveness and comparing faces

Input Example

https://faceid.tencentcloudapi.com/?Action=LivenessCompare
&ImageBase64=<ImageBase64>
&VideoBase64=<VideoBase64>
&LivenessType=SILENT
&<Common request parameters>

Output Example

{
  "Response": {
    "Result": "Success",
    "Description": "Success",
    "BestFrameBase64": "Imagebase64",
    "BestFrameList": [
      "Imagebase64"
    ],
    "Sim": 89.88,
    "RequestId": "f904f4cf-75db-4f8f-a5ec-dc4f942c7f7a"
  }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation.ActionCloseEye No motions of eye closing are detected.
FailedOperation.ActionFaceClose The face is too close to the screen.
FailedOperation.ActionFaceFar The face is too far from the screen.
FailedOperation.ActionFaceLeft The face is too far left from the screen.
FailedOperation.ActionFaceRight The face is too far right from the screen.
FailedOperation.ActionFirstAction The first motion is not detected.
FailedOperation.ActionLightDark The lighting is too dim.
FailedOperation.ActionLightStrong The lighting is too strong.
FailedOperation.ActionNodetectFace Failed to detect a full face.
FailedOperation.ActionOpenMouth No motions of mouth opening are detected.
FailedOperation.CompareFail Comparison failed.
FailedOperation.CompareLowSimilarity The comparison similarity did not reach the passing standard.
FailedOperation.CompareSystemError Error calling the comparison engine API.
FailedOperation.FileSaveError Failed to store the file. Please try again later.
FailedOperation.IdFormatError The ID number entered is incorrect.
FailedOperation.IdNameMisMatch The name and ID number do not match. Please check and try again.
FailedOperation.IdNoExistSystem The number is not in the library. Please go to the applicable household registrar for check.
FailedOperation.IdPhotoNoExist The photo is not in the library. Please go to the applicable household registrar for check.
FailedOperation.IdPhotoPoorQuality The ID photo resolution is too low. Please upload a new one.
FailedOperation.IdPhotoSystemNoanswer Failed to return a photo from the customer library or authentication center. Please try again later.
FailedOperation.LifePhotoDetectFaces Multiple