All Products
Search

This Product

    ID Verification:FACE_COMPARE.

    Document Center

    ID Verification:FACE_COMPARE.

    Last Updated:Jun 24, 2026

    Integrate FaceCompareV2 through the server-side API to compare faces in uploaded images.

    API overview

    • API operation: FaceCompareV2

    • Request method: HTTPS POST

    • Description: Compares faces using image data and other information submitted in a server-side API call.

    • QPS limit: Each API has a dedicated QPS limit. For details, see QPS limits of ID Verification server-side APIs.

    • Endpoints:

      Note

      • Benefits of internal network access: An internal network enables private communication between Alibaba Cloud services in the same region. If your application server is also in the same region, use the internal network endpoint to access the ID Verification service for a more secure and stable connection. 

      • Optimization for overseas access: Network conditions outside the Chinese mainland can be complex. To reduce latency and minimize request failures, optimize your integration by following the best practices in Server-side Network Latency Analysis and Optimization.

      Singapore

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

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

      Indonesia (Jakarta)

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

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

      Malaysia (Kuala Lumpur)

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

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

      China (Hong Kong)

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

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

    Online debugging and integration

    Note

    Before you debug or integrate, read the Debug and integrate server-side APIs with OpenAPI guide to understand how to call APIs on the OpenAPI platform and how to obtain the SDK.

    You can use OpenAPI Explorer to run and debug this API directly, and generate this API's SDK code example.

    Image requirements

    • Supported image formats: JPG, JPEG, and PNG.

    • Image size: Recommended 50–100 KB; maximum 1 MB.

    • Image resolution: Must be at least 640 x 480 pixels (height x width) and no more than 1920 x 1080 pixels. For optimal results, we recommend scaling the shorter side to 720 pixels and using a compression ratio greater than 0.9. Images must be in portrait orientation (height greater than width), as landscape images may reduce detection accuracy.

      Note

      Converting an image to base64 format typically increases its data size. If you pass the image as a base64-encoded string, ensure the original image is no larger than 0.6 MB to stay within the 1 MB data transfer limit.

    • Image quality recommendations:

      • The face must be complete, clear, and unobstructed. The subject should be facing the camera directly. We recommend using images from a front-facing camera.

      • The face must occupy more than 60% of the total image area. Smaller faces may reduce detection accuracy.

      • If an image contains multiple faces, the algorithm processes the largest one by default. For best results, avoid images with multiple faces.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    MerchantBizId

    String

    Yes

    Unique business ID for troubleshooting. Up to 32 alphanumeric characters. Must be unique per request.

    e0c34a77f5ac40a5aa5e6ed20c35****

    SourceFacePicture

    String

    No

    Note

    You can choose any one of the three upload methods.

    The base64-encoded string of the source face image.

    Note

    Ensure the image size does not exceed the specified limits.

    base64 string

    SourceFacePictureUrl

    String

    URL of the source face image. Must be publicly accessible over HTTP or HTTPS.

    https://***

    SourceFacePictureFile

    InputStream

    File stream of the portrait image.

    For specific integration methods, see File uploads with the Advance interface.

    TargetFacePicture

    String

    No

    Note

    You can choose any one of the three upload methods.

    The base64-encoded string of the target face image.

    Note

    Ensure the image size does not exceed the specified limits.

    base64 string

    TargetFacePictureUrl

    String

    URL of the target face image. Must be publicly accessible over HTTP or HTTPS.

    https://***

    TargetFacePictureFile

    InputStream

    Base image for comparison: the file stream of the portrait image in the base image.

    For specific integration methods, see File uploads with the Advance interface.

    FaceQualityCheck

    String

    No

    Enables face quality inspection. Disabled by default. Valid values:

    • N: Disabled (default).

    • Y: Enabled.

    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

    Parameter

    Type

    Description

    Example

    HTTP status code

    Integer

    HTTP status code.

    200

    HTTP body

    RequestId

    String

    Request ID.

    130A2C10-B9EE-4D84-88E3-5384FF0****

    Code

    String

    Return code: For more information, see Server-side HTTP status codes.

    Success

    Message

    String

    A detailed description of the response code.

    success

    Result.TransactionId

    String

    Unique ID of the authentication request.

    08573be80f944d95ac812e019e36****

    Result.Passed

    String

    Final authentication result. Valid values:

    • Y: pass

    • N: fail

    Y

    Result.FaceComparisonScore

    String

    Face comparison score, ranging from 0 to 100.

    52.57