tencent cloud

eKYC

DocumentationeKYCAPI DocumentationAI Face Shield (Pure API) APIsDetectAIFakeFaces

DetectAIFakeFaces

Download
Focus Mode
Font Size
Last updated: 2026-05-22 17:06:23

1. API Description

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

Based on the multimodal AI large model algorithm, it provides anti-attack detection capabilities for facial images and videos. It can effectively identify highly simulated AIGC face-changing, high-definition remakes, batch black market attacks, watermarks and other attack traces, and enhance the anti-counterfeiting security capabilities of images and videos.

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

Import the face image or facial video to be detected (currently only single face detection is supported) in base64 encoding. If your scenario involves both video and image, we recommend using video for detection. For better detection results, please note the following input data limits and suggestions:

  • base64 value of the image:
    Recommend an overall image resolution of 480x640, with the face size no less than 100x100, captured by the mobile front camera.
    The size of the base64-encoded image data should not exceed 3M, with a maximum of 10M. Only jpg and png formats are supported.
    Please use the standard base64 encoding method (with = padding). Refer to RFC4648 for the coding specification.

  • base64 value of the video:
    The size after base64 encoding should be within 8M, with a maximum of 10M. Supported formats include mp4, avi, and flv, captured by the mobile front camera.
    Video duration is recommended to be 2–5s, with a maximum of 20s.
    Video resolution is recommended at 480x640 (maximum support for 720p), with a frame rate between 25fps and 30fps.
    Please use the standard base64 encoding method (with = padding). Refer to RFC4648 for the coding specification.

If you do not use Encryption for secure transmission, this field is a required parameter.
FaceInputType No Integer

Passed in type.

  • Value ranges from 1 to 2:
    1: Passed in image type.
    2: Passed in video type.
    Other: Return error code InvalidParameter.

If you do not use Encryption for encrypting transmission, this field is mandatory.
Encryption No Encryption

Whether to encrypt the entire request information.

  • Supported encryption algorithms: AES-256-CBC, SM4-GCM.
  • The user with encryption requirements can use this parameter. For details, please click the left-side link.
EncryptedBody No String

Encrypted ciphertext.

  • The data format before encryption is as follows: {"FaceInput":"AAAAA","FaceInputType":1}.

3. Output Parameters

Parameter Name Type Description
AttackRiskLevel String

Detection result for the input image/video to check the existence of face spoofing attack.

  • Low: Low attack risk.
  • Mid: Moderately suspected attack.
  • High: Highly suspected attack.

It is advisable to judge as interception when the return value is High, and pass for Mid and Low to better balance security and pass rate.
AttackRiskDetailList Array of AttackRiskDetail

List of suspected attack traces detected. It is returned only when AttackRiskLevel is High or Mid.

  • Description: Return an empty array if no attack traces are detected.
  • This output parameter is for result determination reference. The result of AttackRiskLevel is still recommended for actual use.
ExtraInfo ExtraInfo

Return additional information (including detailed information of cache hit templates).
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 Unencrypted Request Example

Input Example

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

{
    "FaceInputType": 1,
    "FaceInput": "VBORw0KGgoAAAANSUhEUgAAAkYAAAI9CAYAAADfOLduAAABQ2lDQ1BJQ0MgUHJvZmlsZQAAKJFjYGASSCwoyGFhYGDIzSspCnJ3UoiIjFJgf87AziDBwMcgwqCQmFxc4BgQ4ANUwgCjUcG3awyMIPqyLsgsz5I1BWZcn/xff7Y4dPvimWmY6lEAV0pqcTKQ/gPEyckFRSUMDIwJQLZyeUkBiN0CZIsUAR0FZM8AsdMh7DUgdhKEfQCsJiTIGci+AmQLJGckpgDZT4BsnSQk8XQkNtReEOD0CFBwNTI3LiTgVpJBSWpFCYh2zi+oLMpMzyhRcASGUKqCZ16yno6CkYGRMQMDKLwhqj/fAIcjoxgHQqzwKgODhTyQ8RQhlniBgWH3OgYG4Z8IMWUDBgYeoGn7/AsSixLhDmD8xlKcZmwEYXNvZ2Bgnfb//+dwBgZ2TQaGv9f///+9/f//v8sYGJhvMTAc+AYADqxgzYM88zoAAAA4ZVhJZk1NACoAAAAIAAGHaQAEAAAAAQAAABoAAAAAAAKgAgAEAAAAAQAAAkagAwAEAAAAAQAAAj0AAAAAi/M5dAAAQABJREFUeAHsvWd35EiSbYsIRlCkViW6pmq6Wry71vz/fzEf3n2fpufd"
}

Output Example

{
    "Response": {
        "AttackRiskDetailList": [
            {
                "Type": "SuspectedWatermark"
            }
        ],
        "AttackRiskLevel": "High",
        "RequestId": "2dd93e6f-5121-4bac-8c64-d6ad646663d2"
    }
}

Example2 Full Body Encryption Request Example

Example of a full-body encrypted request

Input Example

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

{
    "Encryption": {
        "Algorithm": "AES-256-CBC",
        "EncryptList": [
            "EncryptionBody"
        ],
        "CiphertextBlob": "qwRTgn+52FAvnfrGL1oPBsXG4FLBd42YRw",
        "Iv": "vqfsaEOpGJESA=="
    },
    "EncryptedBody": "v32onREKL6bk6WHOGFEjE2M6kvqybGCVTjlm"
}

Output Example

{
    "Response": {
        "AttackRiskDetailList": [
            {
                "Type": "SuspectedWatermark"
            }
        ],
        "AttackRiskLevel": "High",
        "RequestId": "2dd93e6f-5121-4bac-8c64-d6ad646663d2"
    }
}

Example3 Exception Example

Image decoding failed

Input Example

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

{
    "FaceInputType": 2,
    "FaceInput": "AAAAHGZ0eXBtcDQyAAAAAWlzb21tcDQxbXA0MgAADXNtb292AAAAbG12aGQAAAAA2qNvttqjb7cAAB9AAACYFgABAAABAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADAAAJ/XRyYWsAAABcdGtoZAAAAAHao2+22qNvtwAAAAEAAAAAAACYFgAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAADwAAAAtAAAAAAACRlZHRzAAAAHGVsc3QAAAAAAAAAAQAAmBYAAAAUAAEAAAAACXVtZGlhAAAAIG1kaGQAAAAA2qNvttqjb7cAAAJYAAALaFXEAAAAAAAxaGRscgAAAAAAAAAAdmlkZQAAAAAAAAAAAAAAAENvcmUgTWVkaWEgVmlkZW8AAAAJHG1pbmYAAAAUdm1oZAAAAAEAAAAAAAAAAAAAACRkaW5mAAAAHGRyZWYAAAAAAAAAAQ"
}

Output Example

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

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.CoveredFace The face in the picture is blocked, please upload a picture without any blockage
FailedOperation.DetectEngineSystemError The service engine call failed, please try again
FailedOperation.ImageDecodeFailed Image decoding failed.
FailedOperation.IncompleteFace No complete face was detected. Please enter a complete face image.
FailedOperation.PoorImageQuality The image quality is too poor, please check the image quality
FailedOperation.UnKnown Unknown internal error.
FailedOperation.VideoDecodeFailed Video decoding abnormality
FailedOperation.VideoDurationExceeded The video duration is too long. The maximum video duration supported by the current interface is 20s.
InvalidParameter Invalid parameter.
InvalidParameterValue Incorrect parameter value.
RequestLimitExceeded Number of requests exceeds the frequency limit.
UnauthorizedOperation.Arrears The account is in arrears.
UnauthorizedOperation.ChargeStatusException The billing status is abnormal.
UnauthorizedOperation.Nonactivated The service has not been activated.
Previous Topic: GetWebVerificationResultIntlNext Topic: IdCardVerification

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback