All Products
Search

This Product

    ID Verification:FACE_LIVENESS_MIN.

    Document Center

    ID Verification:FACE_LIVENESS_MIN.

    Last Updated:Aug 20, 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 quality recommendations:

      • Face must be complete, clear, unobstructed, and front-facing. Use a front-facing camera.

      • Face must occupy more than 60% of the image area. Smaller faces reduce accuracy.

      • Multiple faces: the algorithm processes the largest one. Avoid multi-face images.

    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
}