Last updated: 2020-06-24 11:06:59

1. API Description

Domain name for API request:

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:

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 value of a photo for face comparison;
Base64-encoded image data is up to 3 MB. Only JPG and PNG formats are supported.
VideoBase64 Yes String Base64 value of a video for liveness detection;
The size after Base64-encoding cannot exceed 5 MB. MP4, AVI, and FLV formats are supported.
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.
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Face comparison for silent liveness detection

Input Example
&<common request parameters>

Output Example

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

5. Developer Resources

API Explorer

This tool allows online call, signature authentication, SDK code generation and quick search of APIs to greatly improve the efficiency of using TencentCloud APIs.


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 faces are detected.
FailedOperation.LifePhotoDetectFake Real person comparison failed.
FailedOperation.LifePhotoDetectNoFaces Failed to detect a full face.
FailedOperation.LifePhotoPoorQuality The resolution of the image passed in is too low. Please upload a new one.
FailedOperation.LifePhotoSizeError The image passed in is too large or too small.
FailedOperation.LipFaceIncomplete The face is not fully exposed.
FailedOperation.LipMoveSmall The lip movement range is too small.
FailedOperation.LipNetFailed Failed to pull the video. Please try again.
FailedOperation.LipSizeError The video is empty or its size is inappropriate. The recording duration should be about 6 seconds.
FailedOperation.LipVideoInvalid The video format is incorrect.
FailedOperation.LipVideoQuaility The video definition is too low.
FailedOperation.LipVoiceDetect No sound is detected.
FailedOperation.LipVoiceLow The volume of the video is too low.
FailedOperation.LipVoiceRecognize Speech recognition failed.
FailedOperation.LivessBestFrameError Face detection failed. Unable to extract the photo for comparison.
FailedOperation.LivessDetectFail Liveness detection failed.
FailedOperation.LivessDetectFake Suspected spoofed recording.
FailedOperation.LivessSystemError Error calling the liveness engine API.
FailedOperation.LivessUnknownError Video-based real person detection failed.
FailedOperation.NameFormatError The name entered is incorrect.
FailedOperation.SilentDetectFail Real person detection failed.
FailedOperation.SilentThreshold Real person detection did not reach the passing standard.
FailedOperation.SilentTooShort The video is too short. Please capture a video longer than 2 seconds.
FailedOperation.UnKnown Unknown internal error.
InvalidParameter Invalid parameter.
InvalidParameterValue Incorrect parameter value.
UnauthorizedOperation Unauthorized operation.
UnauthorizedOperation.Arrears The account is in arrears.
UnauthorizedOperation.NonAuthorize Identity verification has not been completed for the account.
UnauthorizedOperation.Nonactivated The service has not been activated.
UnsupportedOperation Unsupported operation.

Was this page helpful?

Was this page helpful?

  • Not at all
  • Not very helpful
  • Somewhat helpful
  • Very helpful
  • Extremely helpful
Send Feedback