All Products
Search

This Product

    ID Verification:FACE_CROSS_COMPARE

    Document Center

    ID Verification:FACE_CROSS_COMPARE

    Last Updated:Feb 26, 2026

    This topic describes how to integrate the FACE_CROSS_COMPARE service using only server-side APIs. You can use this service to verify whether three input face images belong to the same person.

    API description

    • Operation name: FaceCrossCompareIntl

    • Request method: HTTPS POST

    • Description: This operation verifies whether three input face images belong to the same person.

    • This API operation has a dedicated QPS limit. For more information, see QPS limits for ID Verification server-side API operations.

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

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

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

      Indonesia

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

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

      China (Hong Kong)

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

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

      Malaysia (Kuala Lumpur)

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

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-3.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.

    In OpenAPI Explorer, you can run this API operation to debug it and generate SDK code examples.

    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

    Note

    Provide image data in one of these ways:

    • Use SourceFacePicture to upload the Base64-encoded image.

    • Use SourceFacePictureUrl to provide the image URL.

    Choose only one method. If using Base64, avoid large images.

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product solution to integrate. Set to FACE_CROSS_COMPARE.

    FACE_CROSS_COMPARE

    SceneCode

    String

    No

    A custom business scenario ID.

    1234567890

    MerchantBizId

    String

    Yes

    A custom unique business identifier used for troubleshooting. Must be 32 characters long and contain only letters and numbers. Ensure uniqueness.

    e0c34a77f5ac40a5aa5e6ed20c35****

    CompareModel

    String

    No

    Comparison mode:

    • 0 — Chain comparison (default): Compare A with B, then B with C.

    • 1 — Loop comparison: Compare A with B, B with C, and C with A.

    0

    SourceAFacePicture

    String

    No

    The Base64-encoded face image.

    base64

    SourceAFacePictureUrl

    String

    No

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

    https://www.xxx.com/1.jpg

    SourceBFacePicture

    String

    No

    The Base64-encoded face image.

    base64

    SourceBFacePictureUrl

    String

    No

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

    https://www.xxx.com/1.jpg

    SourceCFacePicture

    String

    No

    The Base64-encoded face image.

    base64

    SourceCFacePictureUrl

    String

    No

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

    https://www.xxx.com/1.jpg

    FaceVerifyThreshold

    String

    No

    The face matching threshold. This is a reserved system parameter. Custom values are not supported.

    0.4

    Response data

    Name

    Type

    Description

    Example value

    HTTP Status Code

    Integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    String

    The unique ID of the request.

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

    Message

    String

    Returns a detailed description of the code.

    success

    Code

    String

    Response code.

    Success

    Result.FacePassed

    String

    The final verification result. Valid values:

    • Y: Passed

    • N: Failed

    Y

    FaceComparisonScoreA2B

    number<double>

    Comparison score of A versus B. Range: 0 to 1.

    0.9

    FaceComparisonScoreC2A

    number<double>

    Comparison score of C versus A. Range: 0 to 1.

    0.9

    FaceComparisonScoreB2C

    number<double>

    Comparison score of B versus C. Range: 0 to 1.

    0.9

    Result.TransactionId

    String

    The unique ID of the verification request.

    08573be80f944d95ac812e019e36****

    Response codes

    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 images using both Base64 and URL methods simultaneously.

    401

    DownloadTimeout

    The image download from the URL timed out.

    403

    Forbidden.RAMUserAccessDenied

    Grant the AliyunAntCloudAuthFullAccess permission to the 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.