All Products
Search

This Product

    ID Verification:FACE_LIVENESS_MIN_PRO.

    Document Center

    ID Verification:FACE_LIVENESS_MIN_PRO.

    Last Updated:Jun 24, 2026

    FACE_LIVENESS_MIN_PRO is a server-side face liveness API powered by the Qwen-VL multimodal model. It analyzes face images for forgery risks. For higher security, use the App or Web SDK.

    API reference

    • API name: FaceLivenessV2

    • Request method: HTTPS POST

    • Detects liveness in face images.

    • QPS limit: Each API has a dedicated QPS limit. For details, see QPS limits of ID Verification server-side APIs.

    • Service endpoint:

      Note

      • Benefits of internal network access: An internal network enables private communication between Alibaba Cloud services in the same region. If your application server is also in the same region, use the internal network endpoint to access the ID Verification service for a more secure and stable connection. 

      • Optimization for overseas access: Network conditions outside the Chinese mainland can be complex. To reduce latency and minimize request failures, optimize your integration by following the best practices in Server-side Network Latency Analysis and Optimization.

      Singapore

      • Public endpoint: cloudauth-intl.ap-southeast-1.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

      Indonesia (Jakarta)

      • Public endpoint: cloudauth-intl.ap-southeast-5.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

      China (Hong Kong)

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

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

      Malaysia (Kuala Lumpur)

      • Public endpoint: cloudauth-intl.ap-southeast-3.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

    Online debugging and integration

    Note

    Before you debug or integrate, read the Debug and integrate server-side APIs with OpenAPI guide to understand how to call APIs on the OpenAPI platform and how to obtain the SDK.

    You can use OpenAPI Explorer to directly run this API for debugging, and generateSDK Code Examples.

    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 code. Fixed value: FACE_LIVENESS_MIN_PRO.

    FACE_LIVENESS_MIN_PRO

    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.

    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 data

    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 ID of the verification 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:

    • Y: Passed.

    • N: Failed.

    Y

    Result.SubCode

    String

    The authentication result description. For more information, see ResultObject.SubCode error codes.

    200

    Result.ExtFaceInfo

    Object

    Silent liveness detection details in JSON. Fields: ExtFaceInfo Fields.

    {
  "FaceQualityScore": 76.69,
  "OcclusionResult": "N",
  "FaceAttack": "Y",
  "SharpnessScore": 60.78,
  "KaOcclusionScore": 100,
  "FaceGender": "M",
  "OcclusionScore": 99.99,
  "FaceAge": 28,
  "IlluminationScore": 97.43
}

    ResultObject.SubCode error codes

    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

    FaceAge

    Integer

    Predicted age. May be empty if prediction fails.

    30

    FaceGender

    String

    Predicted gender. May be empty if prediction fails.

    • M: Male.

    • F: Female.

    M