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:
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.
China (Hong Kong)
Public endpoint:
cloudauth-intl.cn-hongkong.aliyuncs.comInternal endpoint:
cloudauth-intl-vpc.cn-hongkong.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 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), 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. 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:
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 |
|
|
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. |
|
|
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.
| 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:
| |