FACE_COMPARE - ID Verification - Alibaba Cloud Documentation Center

This topic describes how to integrate the FaceCompare feature using only the server-side API.

API description

API operation: FaceCompare
Request method: HTTPS POST
Description: This API operation performs a face comparison using image data and other information that is passed in a server-side API call.
QPS limit: This API is subject to an exclusive queries per second (QPS) limit. For more information, see ID Verification server-side API QPS limits.
Endpoints:
Note
An internal network is a private communication network between Alibaba Cloud products in the same region. If your application server is deployed in an Alibaba Cloud region, you can use the internal endpoint to access the ID Verification service. This provides a more secure and stable network connection.
China (Hong Kong)
- Public endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com
- Internal same-region endpoint: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
Indonesia
- Public endpoint: cloudauth-intl.ap-southeast-5.aliyuncs.com
- Internal same-region endpoint: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

Note

Before you debug and integrate, read the Use OpenAPI Explorer to debug and integrate server-side API operations document. It explains how to call API operations on the OpenAPI platform and how to obtain the SDK and its sample code.

You can use OpenAPI Explorer to debug this API operation, and generate SDK code examples.

Image format: JPG, JPEG, or PNG.
Image size: Recommended 50 KB to 100 KB, maximum 1 MB.
Image resolution: The resolution must be between 640 × 480 pixels (height × width) and 1920 × 1080 pixels. We recommend scaling the short side to 720 pixels with a compression ratio greater than 0.9. The photo height must be greater than the width. An image with a width greater than its height may affect detection results.
Note
When you pass parameters in base64 format, ensure that the original image size does not exceed 0.6 MB to stay within the 1 MB data transmission limit.
Image quality recommendations:
- The face must be complete, clear, and unobstructed. The subject must be facing the camera directly. We recommend using images captured by the front-facing camera.
- The face should occupy more than 60% of the image area. A smaller face reduces the detection accuracy.
- If an image contains multiple faces, the algorithm crops the largest face by default. We recommend that you avoid using images with multiple faces.

Name	Type	Required	Description	Example
MerchantBizId	String	Yes	A custom unique business ID used for troubleshooting. It can be a combination of up to 32 letters and digits. Make sure that the ID is unique.	e0c34a77f5ac40a5aa5e6ed20c35****
SourceFacePicture	String	Yes	The Base64 encoding of the portrait photo. Note If you use this method to pass the image, check the image size. Do not pass an oversized image.	Base64 encoding
SourceFacePictureUrl	String	No	The URL of the portrait photo. The URL must be an HTTP or HTTPS link accessible over the Internet. Note You must specify either SourceFacePicture or SourceFacePictureUrl.	https://***
TargetFacePicture	String	No	The Base64 encoding of the base photo. Note If you use this method to pass the image, check the image size. Do not pass an oversized image.	Base64 encoding
TargetFacePictureUrl	String	No	The URL of the base portrait photo. The URL must be an HTTP or HTTPS link accessible over the Internet. Note You must specify either TargetFacePicture or TargetFacePictureUrl.	https://***

Name		Type	Description	Example
HTTP Status Code		Integer	The HTTP status code.	200
HTTP Body	RequestId	String	The request ID.	130A2C10-B9EE-4D84-88E3-5384FF0****
	Code	String	The response code.	Success
	Message	String	The detailed description of the response code.	success
	Result.TransactionId	String	The unique ID of the authentication request.	08573be80f944d95ac812e019e36****
	Result.Passed	String	The final authentication result. Valid values: Status: Passed Status: Failed	Y
	Result.FaceComparisonScore	String	The face comparison score. The value ranges from 0 to 100.	52.57

HTTP Status Code	Code	Description
200	Success	The request was successful.
400	MissingParameter	A parameter cannot be empty.
400	InvalidParameter	The parameter is invalid.
401	NoFaceDetected	Feature extraction failed for the face in the custom source image. Upload a different image.
401	UnqualifiedPhoto	The uploaded image is unreadable or its resolution does not meet the requirements. Replace the image. Make sure that the photo is clear, properly exposed, complete, and unobscured, and that the subject's head has no significant tilt.
401	ToolargeImage	The image is too large. Compress the image or use a different upload method.
401	DataDuplication	You passed both SourceFacePicture and SourceFacePictureUrl, or you passed both TargetFacePicture and TargetFacePictureUrl.
401	DownloadTimeout	The image download from the URL timed out.
403	Forbidden.RAMUserAccessDenied	Grant the AliyunAntCloudAuthFullAccess permission to the Resource Access Management (RAM) user. For more information, see Grant a RAM user permissions to access the service.
403	Forbidden.AccountAccessDenied	Make sure that you have activated ID Verification and that your account does not have an overdue payment.
403	Throttling.Api	The API call is blocked by throttling.
500	InternalError	An internal system error occurred. Contact technical support.