All Products
Search
Document Center

ID Verification:FACE_LIVENESS_MIN.

Last Updated:Oct 24, 2026

FACE_LIVENESS_MIN is an API-based liveness detection service that identifies basic presentation attacks — such as screen replay and printed photos — from pre-captured face images. For higher security, integrate the App or Web SDK, or switch to FACE_LIVENESS_MIN_PRO.

API description

  • API name: FaceLivenessV2

  • Request method: HTTPS POST

  • Performs liveness detection on face images.

  • QPS limit: Each API has its own QPS limit. For more information, see QPS limits of ID Verification server-side APIs.

  • Service endpoint:

    Note
    • Benefits of internal network access: An internal network is a private communication network connecting Alibaba Cloud products within the same region. If your application server is deployed in the same region, use the internal endpoint to access the ID Verification service for enhanced security and stability.

    • Optimizing overseas access: Overseas network environments can be complex. Refer to Optimize server network latency to tune your integration and reduce network latency and request failures.

    China (Hong Kong)

    • Public endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com

    • Internal endpoint: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

Online debugging and integration

Note

Before debugging and integration, read the Use OpenAPI document to learn how to call APIs on the OpenAPI platform and obtain the SDK.

You can run this API in OpenAPI Explorer to debug it and generate an SDK Code Samples.

Face image format requirements

  • Submit face images using one of three methods:

    • Base64 mode: FacePictureBase64

    • URL mode: FacePictureUrl

    • File stream mode: FacePictureFile

  • Image format: JPG, JPEG, PNG.

  • Image size: Recommended 50–100 KB, maximum 1 MB.

  • Image resolution: Maximum 1920*1080 (height × width), minimum 640*480 (height × width). Scale the shorter side to 720 px with compression ratio > 0.9. Height must exceed width; landscape orientation may reduce accuracy.

    Note

    Base64 encoding inflates file size. Keep the original image under 0.6 MB to stay within the 1 MB transfer limit.

  • Image input specifications

    This product uses only API calls. The detection accuracy depends on the quality and composition of the input image. Ensure that the input face photos meet the following requirements.

    Recommended image types

    • Close-ups or half-body photos: Use images with a size and aspect ratio similar to standard face photos captured in SDK mode. Images from a front-facing camera are preferred.

    • Appropriate face-to-image ratio: The face must occupy more than 60% of the total image area. The facial features must be clearly visible with no major obstructions.

    • Even lighting: Avoid images that are overexposed, underexposed, or have noticeably uneven lighting.

    Unsupported or problematic image types

    Do not pass the following image types directly to the API. These image types can lower the detection accuracy or prevent a valid assessment.

    • Full-body photos: The face is too small in the image and provides insufficient facial feature information.

    • Photos of a person holding an ID: The image contains a complex background and other objects that can interfere with the forgery threat assessment.

    • Photos of an ID document: Static portraits on documents, such as ID cards or passports, are secondary images. These images can cause incorrect or failed detections.

    • Group photos: The image contains multiple faces, which makes it impossible to specify a clear detection target.

Request parameters

Name

Type

Required

Description

Example

ProductCode

String

Yes

Product solution. Set to FACE_LIVENESS_MIN.

FACE_LIVENESS_MIN

MerchantBizId

String

Yes

Custom business identifier for tracking. Letters and digits, max 32 characters. Must be unique.

Note

Uniqueness is not enforced server-side. Ensure unique values for accurate tracking.

e0c34a77f5ac40a5aa5e6ed20c35****

MerchantUserId

String

Yes

Custom user identifier (e.g., mobile number or email). Hash this value before submission.

123456789

FacePictureBase64

String

No

Base64-encoded face image. Verify size before submission to avoid exceeding the 1 MB limit.

base64

FacePictureUrl

String

No

Publicly accessible URL of the face image.

https://***

FacePictureFile

InputStream

No

Face image as a file stream.

The InputStream object of the face image

FaceQualityCheck

String

No

Enables face quality inspection. Disabled by default. Valid values:

  • N: Disabled (default).

  • Y: Enabled.

When enabled, the system blocks low-quality photos (blurry, occluded) from comparison. Recommended when higher accuracy is required or to reduce invalid requests. Returns 401 (UnqualifiedPhoto) for blocked images.

N

Response parameters

Name

Type

Description

Example

HTTP Status Code

Integer

HTTP status code.

200

HTTP Body

RequestId

String

Request ID.

130A2C10-B9EE-4D84-88E3-5384FF0****

Result.TransactionId

String

Unique identifier for the authentication process.

hksb7ba1b28130d24e015d694361****

Code

String

Return code: For more information, see Server-side HTTP status codes.

Success

Message

String

This section provides detailed descriptions of the return codes.

Success

Result.Passed

String

Authentication result. Valid values:

  • Y: Passed

  • N: Not passed

Y

Result.SubCode

String

The description of the authentication result. For more information, see Error codes for ResultObject.SubCode.

200

Result.ExtFaceInfo

String

The result information related to silent liveness detection. For the JSON format, see the example on the right. For more information, see ExtFaceInfo.

{
 "faceAttack": "N",
 "faceQualityScore": 88.62,
 "faceOcclusionResult": "N"
}

Error codes for ResultObject.SubCode

Error Code

Billed

Description and Suggestion

200

Yes

The authentication passed.

205

Yes

Risk detected in liveness detection.

ExtFaceInfo

Name

Type

Description

Example

FaceQualityScore

Double

Face quality score. Range: 0–100. Higher is better.

88.62

OcclusionScore

Double

Occlusion sub-score. Range: 0–100. Higher is better.

99.99

KaOcclusionScore

Double

Key-area occlusion sub-score. Range: 0–100. Higher is better.

100

IlluminationScore

Double

Illumination sub-score. Range: 0–100. Higher is better.

97.43

SharpnessScore

Double

Sharpness sub-score. Range: 0–100. Higher is better.

60.78

FaceAttack

String

Whether a liveness attack is detected.

  • Y: An attack is detected.

  • N: No attack is detected.

N

FaceAttributeInfo

String

Detects the facial attributes of the main face in an input image. The main face is the one that is largest, clearest, and closest to the camera. The detection results are returned as a string. You can use this string to make decisions about the content.

The returned fields are defined as follows:

  • gender: The gender of the main entity. A value of 1 indicates male, and 0 indicates female.

  • glasses: Indicates whether the main entity is wearing glasses. A value of 1 indicates that glasses are detected, and 0 indicates that they are not.

  • hat: Indicates whether the main entity is wearing a hat. This includes headscarves or veils. A value of 1 indicates that a hat is detected, and 0 indicates that it is not.

  • mask: Indicates whether the main entity is wearing a mask. A value of 1 indicates that a mask is detected, and 0 indicates that it is not.

  • tattoo: Indicates whether the main entity has a visible tattoo. A value of 1 indicates that a tattoo is detected, and 0 indicates that it is not.

  • smoking: Indicates whether the main entity is smoking. A value of 1 indicates that smoking is detected, and 0 indicates that it is not.

  • others: Indicates whether people other than the main entity are present. A value of 1 indicates that other people are detected, and 0 indicates that they are not.

  • env: The environment of the main entity, such as an office, factory, hospital, or vehicle. The system currently supports returning office, hospital, factory, vehicle, or other.

  • expression: Indicates whether the main entity has an exaggerated expression. An exaggerated expression is a strong facial expression that is distinct from a natural or calm state. A value of 1 indicates that an exaggerated expression is detected, and 0 indicates that it is not.

  • age: The age of the main entity in years.

{
        gender: 1
        glasses: 0
        hat: 1
        mask: 1
        tattoo: 0
        smoking: 0
        others: 1
        env:office
        expression:1
        age:16
}