tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

LivenessCompare

Last updated: 2024-04-03 11:45:31

    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.
    This API on the legacy version will continue to serve existing users but will be unavailable to new users. We recommend you use VideoLivenessCompare for better service quality.

    A maximum of 100 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: LivenessCompare.
    Version Yes String Common Params. The value used for this API: 2018-03-01.
    Region No String Common Params. This parameter is not required for this API.
    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.
    ImageBase64 No 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.

    Either the ImageUrl or ImageBase64 of the image must be provided. If both are provided, only ImageBase64 will be used.
    ImageUrl No String URL of the image for face comparison. The size of the downloaded image after Base64 encoding can be up to 3 MB. JPG and PNG formats are supported.

    Either the ImageUrl or ImageBase64 of the image must be provided. If both are provided, only ImageBase64 will be used.

    We recommend you store the image in Tencent Cloud, as a Tencent Cloud URL can guarantee higher download speed and stability. The download speed and stability of non-Tencent Cloud URLs may be low.
    ValidateData No String Lip mode: set this parameter to a custom 4-digit verification code.
    Action mode: set this parameter to a custom action sequence (e.g., 2,1 or 1,2).
    Silent mode: do not pass in this parameter.
    Optional No String Optional configuration (a JSON string)
    {
    "BestFrameNum": 2 // Return multiple best screenshots. Value range: 2−10
    }
    VideoBase64 No 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.

    Either the VideoUrl or VideoBase64 of the video must be provided. If both are provided, only VideoBase64 will be used.
    VideoUrl No String URL of the video for liveness detection. The size of the downloaded video after Base64 encoding can be up to 8 MB. It takes no more than 4 seconds to download. MP4, AVI, and FLV formats are supported.

    Either the VideoUrl or VideoBase64 of the video must be provided. If both are provided, only VideoBase64 will be used.

    We recommend you store the video in Tencent Cloud, as a Tencent Cloud URL can guarantee higher download speed and stability. The download speed and stability of non-Tencent Cloud URLs may be low.

    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, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

    4. Example

    Example1 Detecting liveness in silent mode and comparing face

    Input Example

    POST / HTTP/1.1
Host: faceid.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: LivenessCompare
<Common request parameters>

{
    "LivenessType": "SILENT",
    "ImageBase64": "<ImageBase64>",
    "VideoBase64": "<VideoBase64>"
}

    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
    AuthFailure.InvalidAuthorization CAM signature/authentication error.
    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.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy