All Products
Search

This Product

    ID Verification:FACE_COMPARE.

    Document Center

    ID Verification:FACE_COMPARE.

    Last Updated:Sep 18, 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 its own QPS limit. For more information, see QPS limits of ID Verification server-side APIs.

    • Endpoints:

      Note

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

      Asia Pacific SE 1 (Singapore)

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

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

      Asia Pacific SE 5 (Jakarta)

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

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

      Asia Pacific SE 3 (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 debugging and integration, read the Use OpenAPI document to learn how to call APIs on the OpenAPI platform and 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

    • Image format: JPG, JPEG, or PNG.

    • Image size: The recommended size is 50–100 KB, with a maximum of 1 MB.

    • Image resolution: Between 640×480 and 1920×1080 (height × width). For best results, we recommend scaling the shorter side to 720 pixels with a compression ratio greater than 0.9. Prefer portrait-oriented images (height greater than width), as landscape images can reduce detection accuracy.

      Note

      Converting an image to base64 format increases its data size. When passing an image as base64, ensure the original file 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, unobstructed, and facing the camera directly. For best results, use images from a front-facing camera.

      • The face should occupy more than 60% of the image area, as smaller faces can reduce detection accuracy.

      • If an image contains multiple faces, the algorithm processes the largest one by default. Avoid using 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