All Products
Search

This Product

    ID Verification:FaceCompare

    Document Center

    ID Verification:FaceCompare

    Last Updated:Mar 25, 2026

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

    API

    • API operation: FaceCompare

    • Request method: HTTPS POST

    • Description: Compares faces using image data and other information submitted 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.

      Singapore

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

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

      Indonesia

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

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

      Malaysia (Kuala Lumpur)

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

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

      China (Hong Kong)

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

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

    Online debugging and integration

    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 run and debug this API directly, and generate this API's SDK code example.

    Input image format requirements

    • 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.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    MerchantBizId

    String

    Yes

    A unique business ID for troubleshooting, containing up to 32 letters and digits. This ID must be unique for each request.

    e0c34a77f5ac40a5aa5e6ed20c35****

    SourceFacePicture

    String

    Yes

    The base64-encoded string of the source face image.

    Note

    If you use this parameter, ensure the image size does not exceed the specified limits.

    base64 string

    SourceFacePictureUrl

    String

    No

    The URL of the source face image. The URL must be a publicly accessible HTTP or HTTPS URL.

    Note

    You must specify either SourceFacePicture or SourceFacePictureUrl.

    https://***

    TargetFacePicture

    String

    No

    The base64-encoded string of the target face image.

    Note

    If you use this parameter, ensure the image size does not exceed the specified limits.

    base64 string

    TargetFacePictureUrl

    String

    No

    The URL of the target face image. The URL must be a publicly accessible HTTP or HTTPS URL.

    Note

    You must specify either TargetFacePicture or TargetFacePictureUrl.

    https://***

    Response parameters

    Parameter

    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

    A 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: pass

    • N: fail

    Y

    Result.FaceComparisonScore

    String

    The face comparison score. The value ranges from 0 to 100.

    52.57

    Response codes

    HTTP status code

    Code

    Description

    200

    Success

    The request was successful.

    400

    MissingParameter

    A required parameter is missing.

    400

    InvalidParameter

    An invalid parameter was specified.

    401

    NoFaceDetected

    Failed to extract facial features from the source image. Use a different image.

    401

    UnqualifiedPhoto

    The image is unreadable or does not meet resolution requirements. Use a clear, properly exposed, complete, and unobscured image with no significant head tilt.

    401

    ToolargeImage

    The image is too large. Compress the image or provide it by using a URL.

    401

    DataDuplication

    Both a base64 string and a URL were provided for the same image. Provide either the image content or its URL, but not both.

    401

    DownloadTimeout

    The image download from the URL timed out.

    403

    Forbidden.RAMUserAccessDenied

    The RAM user is not authorized to perform this operation. You must grant the AliyunAntCloudAuthFullAccess permission to the RAM user. For more information, see Grant a RAM user permissions to access the service.

    403

    Forbidden.AccountAccessDenied

    Ensure that you have activated ID Verification and that your account has no overdue payments.

    403

    Throttling.Api

    The API call was rejected due to throttling.

    500

    InternalError

    An internal error occurred. Contact technical support for assistance.