tencent cloud



Last updated: 2022-09-05 16:37:37

1. API Description

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

This API is used to pass in URLs of 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.

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 Params. The value used for this API: VideoLivenessCompare.
Version Yes String Common Params. The value used for this API: 2018-03-01.
Region Yes String Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-bangkok, ap-hongkong, ap-singapore, ap-tokyo, eu-moscow.
ImageUrl Yes String The URL of the photo for face comparison. The downloaded image after Base64 encoding can be up to 3 MB and must be in JPG or PNG.

The image must be stored in a COS bucket in the region where the FaceID service resides to ensure a higher download speed and better stability. You can generate an image URL by using CreateUploadUrl or purchase the COS service.
ImageMd5 Yes String The 32-bit MD5 checksum of the image for comparison
VideoUrl Yes String The URL of the video for liveness detection. The downloaded video after Base64 encoding can be up to 8 MB and must be in MP4, AVI, or FLV. It takes no more than 4s to download the video.

The video must be stored in a COS bucket in the region where the FaceID service resides to ensure a higher download speed and better stability. You can generate a video URL by using CreateUploadUrl or purchase the COS service.
VideoMd5 Yes String The 32-bit MD5 checksum of the video
LivenessType Yes String The liveness detection type. Valid values: LIP, ACTION, and SILENT.
LIP: Numeric mode; ACTION: Motion mode; SILENT: silent mode. Select one of them.
ValidateData No String LIP parameter: Pass in a custom 4-digit verification code.
ACTION parameter: Pass in a custom action sequence (2,1 or 1,2).
SILENT parameter: Null.

3. Output Parameters

Parameter Name Type Description
Sim Float The 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 persons are of the same person. You can adjust the threshold according to your specific scenario (the FARs at the thresholds of 70 and 80 are 0.1% and 0.01%, respectively).
Result String The service error code. Success will be returned for success. For error information, see the FailedOperation section in the error code list below.
Description String The service result description
BestFrame FileInfo The best video screenshot after successful verification
Note: This field may return null, indicating that no valid values can be obtained.
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Detecting liveness in silent mode and comparing face

Input Example

&<Common request parameters>

Output Example

    "Response": {
        "Result": "Success",
        "Description": "Success",
        "BestFrame": {
            "Url": "https://intl-reflect-h5-1257237511.cos.ap-guangzhou.myqcloud.com",
            "MD5": "682e24b207acf1825286c1fceef5631c",
            "Size": 9430792
        "Sim": 89.88,
        "RequestId": "f904f4cf-75db-4f8f-a5ec-dc4f942c7f7a"

5. Developer Resources


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 No movement is 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.DownLoadError File download failed.
FailedOperation.DownLoadTimeoutError File download timed out.
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.SilentDetectFail Real person detection failed.
FailedOperation.SilentEyeLiveFail Eye detection failed.
FailedOperation.SilentFaceDetectFail No face is detected in the video.
FailedOperation.SilentFaceQualityFail Low face quality.
FailedOperation.SilentFaceWithMaskFail A face mask is detected.
FailedOperation.SilentMouthLiveFail Mouth detection failed.
FailedOperation.SilentMultiFaceFail Multiple faces are detected in the video.
FailedOperation.SilentPictureLiveFail The video might be spoofed.
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.
Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support