tencent cloud

APIs

DokumentasiAPIsFace RecognitionFace Static Liveness Detection (High-Precision Version) APIsDetectLiveFaceAccurate

DetectLiveFaceAccurate

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-10-20 17:15:46

1. API Description

Domain name for API request: iai.intl.tencentcloudapi.com.

This API is used to perform anti-rephotograph liveness detection on user-uploaded static images to determine whether they are rephotographs.

Compared with existing static liveness detection services, the high-precision version enhances defense against attacks such as HD screens, cropped paper, and 3D masks while maintaining a high real person pass rate. Its attack interception rate is about 4-5 times that of similar types of products in the industry. It also supports face verification in different use cases, meets image-based liveness detection requirements for various scenarios on mobile and PC, and is applicable to different liveness detection applications across industries.

The face static liveness detection (high-precision version) API officially starts billing from 00:00 on August 1, 2022, using the postpaid pay-as-you-go billing mode. For details, see Billing Overview (https://www.tencentcloud.com/document/product/867/17640?from_cn_redirect=1).

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: DetectLiveFaceAccurate.
Version Yes String Common Params. The value used for this API: 2020-03-03.
Region No String Common Params. This parameter is not required.
Image No String

base64 data of the image.

  • The size after base64 encoding must not exceed 5M.
  • For jpg format, the long side pixel must not exceed 4000. For other formats, the long side pixel must not exceed 2000.
  • The aspect ratio of the image should be close to 3:4. The ratio from mobile phone shooting is best.
  • The human face size must be greater than 100X100 pixels.
  • Format support: PNG, jpg, JPEG, and BMP. GIF images are not supported.
Url No String

The Url of the Image.

  • The size of the corresponding Image after base64 encoding must not exceed 5M.
  • For jpg format, the long side pixel must not exceed 4000. For other formats, the long side pixel must not exceed 2000.
  • Either Url or Image must be provided. If both are provided, only use Url.
  • The aspect ratio of the Image should be close to 3:4, which is the best ratio for mobile phone shooting.
  • The human face size must be greater than 100X100 pixels.
  • An Image stored in Tencent Cloud via Url can guarantee higher download speed and stability. It is recommended to store images in Tencent Cloud. The speed and stability of URLs not stored in Tencent Cloud may be affected.
  • Supported Image formats include PNG, jpg, JPEG, and BMP. GIF images are not supported.
FaceModelVersion No String

Algorithm model version used by the face recognition service. Currently, the input parameter supports "3.0".

3. Output Parameters

Parameter Name Type Description
Score Float

Liveness authenticity score.

  • Value range: [0,100].
  • Determine whether it is a rephotograph based on the threshold range corresponding to the liveness score.
  • Currently, the threshold can be divided into [5,10,40,70,90], with a recommended threshold of 40.
  • The higher the score, the closer to a real person and the lower the rephotograph risk.
FaceModelVersion String

Algorithm model version used for face recognition.
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 Failure example of face static liveness detection (high-precision version)

Input Example

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

{
    "Url": "http://test.image.myqcloud.com/testB.jpg"
}

Output Example

{
    "Response": {
        "Error": {
            "Code": "FailedOperation.ImageDecodeFailed",
            "Message": "Image decoding failed."
        },
        "RequestId": "0e77ad29-ad65-4901-9efc-b49a6e0a357b"
    }
}

Example2 Successful example of face static liveness detection (high-precision version)

Input Example

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

{
    "Url": "http://test.image.myqcloud.com/testA.jpg"
}

Output Example

{
    "Response": {
        "Score": 99,
        "FaceModelVersion": "3.0",
        "RequestId": "048a5eb3-f7a9-4c1f-a982-00e90b6b892c"
    }
}

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.ConflictOperation Operation conflict. Do not operate the same Person at the same time.
FailedOperation.DuplicatedGroupDescription Custom description fields in the same person library cannot be repeated.
FailedOperation.FaceSizeTooSmall Face frame size is less than the MinFaceSize setting, and the human face is filtered.
FailedOperation.GroupInDeletedState The current group is being deleted. Please wait.
FailedOperation.GroupPersonMapExist The group already contains the corresponding personnel Id.
FailedOperation.GroupPersonMapNotExist The group does not include the corresponding personnel Id.
FailedOperation.ImageDecodeFailed Image decoding failed.
FailedOperation.ImageDownloadError Image download error.
FailedOperation.ImageFacedetectFailed Face detection failed.
FailedOperation.ImageResolutionExceed The image resolution is too high.
FailedOperation.ImageResolutionTooSmall The short edge resolution of the image is lower than 64 pixels.
FailedOperation.ImageSizeExceed The size of the image after base64 encoding cannot exceed 5 MB.
FailedOperation.RequestLimitExceeded Request frequency exceeds the limit.
FailedOperation.RequestTimeout The backend service timed out.
FailedOperation.RpcFail Rpc call failed.
FailedOperation.SearchFacesExceed The number of retrieved human faces exceeds the limit.
FailedOperation.ServerError Algorithm service exception. Retry.
FailedOperation.UnKnowError Internal error.
InternalError Internal error.
InvalidParameter.InvalidParameter Invalid parameters.
InvalidParameterValue.AccountFaceNumExceed Number of faces in the account exceeds the limit.
InvalidParameterValue.DeleteFaceNumExceed The number of faces to delete exceeds the limit. Each person must contain at least one face.
InvalidParameterValue.FaceModelVersionIllegal Invalid algorithm model version.
InvalidParameterValue.GroupExDescriptionsExceed The person library customized description field array exceeds the length limit. You can create up to 5.
InvalidParameterValue.GroupExDescriptionsNameIdentical The custom description field name in the person library cannot be repeated.
InvalidParameterValue.GroupExDescriptionsNameIllegal The custom description field name of the personnel database contains invalid characters. It can only contain Chinese and English characters, -, _, and digits.
InvalidParameterValue.GroupExDescriptionsNameTooLong Personnel library custom description field name length exceeds the limit.
InvalidParameterValue.GroupFaceNumExceed The number of faces in the person library exceeds the limit.
InvalidParameterValue.GroupIdAlreadyExist Personnel database ID already exists. Personnel database ID cannot be repeated.
InvalidParameterValue.GroupIdIllegal The personnel database ID contains invalid characters. The personnel database ID supports only English, digits, -%@#&_.
InvalidParameterValue.GroupIdNotExist Personnel database ID does not exist.
InvalidParameterValue.GroupIdTooLong Personnel database ID exceeds the length limit.
InvalidParameterValue.GroupIdsExceed The incoming personnel library list exceeds the limit.
InvalidParameterValue.GroupNameAlreadyExist Person library name already exists. Person library name should be unique.
InvalidParameterValue.GroupNameIllegal The personnel database name contains invalid characters. It can only contain Chinese and English characters, -, _, and digits.
InvalidParameterValue.GroupNameTooLong Personnel database name exceeds the length limit.
InvalidParameterValue.GroupNumExceed The number of person libraries exceeds the limit. To add more, contact us.
InvalidParameterValue.GroupNumPerPersonExceed The number of person libraries exceeds the limit. A single person can be added to up to 100 person libraries.
InvalidParameterValue.GroupTagIllegal Personnel database remarks contain invalid characters. Personnel database remarks only support Chinese, English, -, _, and digits.
InvalidParameterValue.GroupTagTooLong Personnel database remarks exceed the length limit.
InvalidParameterValue.ImageEmpty No image is input.
InvalidParameterValue.LimitExceed Number of returns exceeds the limit.
InvalidParameterValue.NoFaceInGroups No human face in the specified group.
InvalidParameterValue.NoFaceInPhoto The image contains no human face.
InvalidParameterValue.OffsetExceed Starting number is too large. Please check the required length of the array.
InvalidParameterValue.PersonExDescriptionInfosExceed The customized description field array exceeds the length limit. Up to 5.
InvalidParameterValue.PersonExDescriptionsNameIdentical The custom description field name of a person cannot be repeated.
InvalidParameterValue.PersonExDescriptionsNameIllegal The custom description field name contains invalid characters. The custom description field name supports only Chinese, English, -, _, and digits.
InvalidParameterValue.PersonExDescriptionsNameTooLong Person custom description field name length exceeds the limit.
InvalidParameterValue.PersonExistInGroup The group already contains the corresponding personnel Id.
InvalidParameterValue.PersonFaceNumExceed The number of faces for a single person exceeds the limit. A single person can contain up to five faces.
InvalidParameterValue.PersonGenderIllegal Error in gender of personnel settings. 0 represents empty, 1 represents man, 2 represents woman.
InvalidParameterValue.PersonIdAlreadyExist Person ID already exists. Person ID should be unique.
InvalidParameterValue.PersonIdIllegal The person ID contains invalid characters. The person ID supports only English, digits, -%@#&_.
InvalidParameterValue.PersonIdNotExist Personnel ID does not exist.
InvalidParameterValue.PersonIdTooLong Person ID exceeds the length limit.
InvalidParameterValue.PersonNameIllegal The person name contains invalid characters. It can only contain Chinese and English characters, -, _, and digits.
InvalidParameterValue.PersonNameTooLong Person name exceeds the length limit.
InvalidParameterValue.SearchPersonsExceed The number of personnel found exceeds the limit.
InvalidParameterValue.UploadFaceNumExceed Upload up to four human faces.
InvalidParameterValue.UrlIllegal The URL format is invalid.
LimitExceeded.ErrorFaceNumExceed The number of human faces exceeds the limit.
MissingParameter.ErrorParameterEmpty The required parameter is empty.
ResourceUnavailable.Delivering The resource is being delivered.
ResourceUnavailable.Freeze The account has been frozen.
ResourceUnavailable.InArrears The account is in arrears.
ResourceUnavailable.LowBalance Insufficient balance.
ResourceUnavailable.NotExist The billing status is unknown. Check whether the service has been activated in the console.
ResourceUnavailable.Recover The resource has been possessed.
ResourceUnavailable.StopUsing Services for the account has been stopped.
ResourceUnavailable.UnknownStatus The billing status is unknown.
ResourcesSoldOut.ChargeStatusException The billing status is abnormal.
UnsupportedOperation.UnknowMethod The method name is unknown.
Topik sebelumnya: DetectFaceSimilarityTopik selanjutnya: DetectFace

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation