FACE_COMPARE - ID Verification - Alibaba Cloud Documentation Center

This topic describes how to integrate the face comparison feature using only the server-side API operation.

API description

API operation: FaceCompare
Request method: HTTPS POST
Description: This API operation performs a face comparison using image data and other information passed in a server-side API call.
This API operation has a dedicated QPS limit. For more information, see QPS limits for ID Verification server-side API operations.
Endpoints:
Note
- Benefits of internal network access: An internal network is a private communication network between Alibaba Cloud products within the same region. If your business server is deployed in the corresponding Alibaba Cloud region, you can use the internal same-region endpoint to access the ID Verification service. This provides more secure and stable communication.
- Optimization suggestions for access from outside China: Network environments outside China can be complex. To optimize your integration solution, reduce network latency, and minimize request failures, see Server-side network latency analysis and optimization.
China (Hong Kong)
- Public network: cloudauth-intl.cn-hongkong.aliyuncs.com
- Internal network: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
Indonesia
- Public network: cloudauth-intl.ap-southeast-5.aliyuncs.com
- Internal network: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

Note

Before you debug and integrate an API operation, see Debug and integrate server-side API operations using OpenAPI Explorer for information about how to call API operations and obtain SDKs and sample code in OpenAPI Explorer.

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

Image format: JPG, JPEG, or PNG.
Image size: 50 KB to 100 KB is recommended. The maximum size is 1 MB.
Image resolution: The resolution must be between 640 × 480 pixels (height × width) and 1920 × 1080 pixels. We recommend scaling the shorter side to 720 pixels with a compression ratio greater than 0.9. The image height should be greater than the width. If the width is greater than the height, detection accuracy may be reduced.
Note
Converting an image to Base64 format increases its data size. To pass parameters in Base64 format, ensure that the original image size does not exceed 0.6 MB to avoid exceeding the 1 MB data transfer limit.
Image quality recommendations:
- The face in the image must be complete, clear, and unobstructed. The subject should be facing the camera directly. We recommend using facial images captured by a front-facing camera.
- The face should occupy more than 60% of the image area. A smaller face may reduce detection accuracy.
- If there are multiple faces in the image, the algorithm crops the largest face by default. We recommend avoiding 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 value
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: Y: Passed N: Not passed	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 can also pass images using Base64 or a link.
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 for assistance.