FACE_LIVENESS_MIN_PRO is a liveness detection (real-person detection) service invoked via an API. It accepts pre-captured face images and leverages the Qwen-VL large model to perform a deepfake risk analysis, which accurately determines whether the input image is of a real person.
Security level notice: The App and Web SDKs provide stronger protection against client-side attacks. If your business scenario requires a high level of security for real-person face verification, prioritize integrating the SDK. This API solution is for scenarios that require high integration flexibility and frontend image capture control.
Solution performance: Before using this API solution, fully evaluate the expected end-user experience and develop corresponding image capture and fallback policies.
Interruption rate differences: The API solution lacks the real-time guidance, action coordination, and environmental adaptation capabilities of the client-side SDK. As a result, it has a lower tolerance for poor image quality, and the interruption rate is typically higher than with the SDK solution. The interruption rate is the probability that a user is asked to retake a photo or that verification is denied. This difference is a result of its technical architecture.
Frontend capture recommendations: Add basic cropping, face detection, and photo-taking guidance logic to your business frontend. Guide users to capture or upload photos that meet the Image Input Specifications. This helps reduce the interruption rate at the source.
Optimization support: Contact your account manager if the interruption rate does not meet your business requirements, or if your scenario must use specific image types, such as certain snapshots or photos from a specific distance. Your account manager can arrange for customized model training using real data from your business scenario. This training increases the recognition pass rate and lowers the interruption rate without compromising security.
API reference
API name: FaceLivenessV2
Request method: HTTPS POST
Detects liveness in 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:
NoteBenefits 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.
Asia Pacific SE 1 (Singapore)
Public endpoint:
cloudauth-intl.ap-southeast-1.aliyuncs.comInternal endpoint:
cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com
Asia Pacific SE 5 (Jakarta)
Public endpoint:
cloudauth-intl.ap-southeast-5.aliyuncs.comInternal endpoint:
cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com
China (Hong Kong)
Public endpoint:
cloudauth-intl.cn-hongkong.aliyuncs.comInternal endpoint:
cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
Asia Pacific SE 3 (Kuala Lumpur)
Public endpoint:
cloudauth-intl.ap-southeast-3.aliyuncs.comInternal endpoint:
cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com
Online debugging and integration
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 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), minimum640*480(height × width). Scale the shorter side to 720 px with compression ratio > 0.9. Height must exceed width; landscape orientation may reduce accuracy.NoteBase64 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 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:
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 |
FaceAttributeCheck | String | No | Face Recognition Configuration: Specifies whether to return additional facial attributes.
The output is returned in `Checkresult` at | 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 | |
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. | | |
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.
| 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:
| |