All Products
Search

This Product

    ID Verification:Initialize

    Document Center

    ID Verification:Initialize

    Last Updated:Jan 31, 2026

    This topic describes how to call the Initialize API operation to start a face liveness verification request.

    Initiate a verification request

    • API operation: Initialize

    • Request method: HTTPS POST

    • Description: Before starting a verification flow, call this API operation to obtain a transactionId. This ID links all API operations in the verification request.

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

    • Endpoint:

      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

    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 debug this API operation in OpenAPI Explorer. You can also generate sample SDK code for this operation.

    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

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product solution to use. The only valid value is FACE_VERIFY.

    FACE_VERIFY

    SceneCode

    String

    No

    A custom ID for the verification scenario. You can use this ID to query related records in the console. The ID can be up to 10 characters in length and can contain letters, digits, and underscores (_).

    1234567890

    MerchantBizId

    String

    Yes

    A custom unique business ID. You can use this ID to track and troubleshoot issues. The ID can be up to 32 characters in length and can contain letters and digits. Make sure the ID is unique.

    Note

    Alibaba Cloud servers do not check the uniqueness of this field. For better tracking, we strongly recommend that you ensure the uniqueness of this field.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    Yes

    The MetaInfo environment parameter. Obtain this parameter using the client SDK. For more information, see Android integration.

    Note

    Do not modify the return value. Pass it through directly.

    		 
    {
    "appVersion": "1",
    "bioMetaInfo": "4.1.0:1150****,0",
    "appName": "com.aliyun.antcloudauth",
    "deviceType": "ios",
    "osVersion": "iOS 10.3.2",
    "apdidToken": "",
    "deviceModel": "iPhone9,1"
}

    MerchantUserId

    String

    Yes

    A custom user ID or another identifier for a specific user, such as a mobile phone number or an email address. We strongly recommend that you desensitize the value of this field in advance, for example, by hashing the value.

    123456789

    FacePictureBase64

    String

    No

    The Base64-encoded face image. If you use the FacePictureBase64 parameter to pass the face image, check the image size. Do not pass an oversized image.

    /9j/4AAQSkZJRgABAQAASASBC****

    FacePictureUrl

    String

    No

    The URL of the face image. The URL must be an HTTP or HTTPS link that is accessible over the public network.

    Note

    If ProductCode is set to FACE_VERIFY, you must specify either FacePictureBase64 or FacePictureUrl.

    https://cn-shanghai-aliyun-cloudauth-****.oss-cn-shanghai.aliyuncs.com/verify/****.jpeg

    SecurityLevel

    String

    No

    The mode that represents different security levels of the verification flow. Valid values:

    • 01: Standard mode. This mode is applicable only to low-threat scenarios with restrictions on device information collection.

    • 02: Safe mode. A relatively strict mode (default).

      Note

      • Safe mode uses the new Device Guard module in the SDK to identify the security of the face-scanning environment based on device information. This effectively enhances the ability to intercept injection attacks. Enable this mode.

      • During development and testing, the environmental characteristics of a test device may cause Device Guard to assess it as a threat, which triggers a verification failure (Subcode 206). To improve testing efficiency, set the mode to '01 Standard mode' during the testing phase. When you go live, switch to '02 Safe mode' to enhance verification security.

    02

    Model

    String

    No

    The type of liveness detection to perform:

    • LIVENESS: Blinking liveness detection (default).

    • PHOTINUS_LIVENESS: Blinking liveness detection and color-based liveness detection (not supported on PCs).

    Note

    For information about the supported SDK versions, see SDK release notes.

    PHOTINUS_LIVENESS

    DocVideo

    String

    No

    Specifies whether to save a verification video.

    • N: No (default).

    • Y: A video of the user's face-scanning process (a 1 to 2 second video file) is collected during the verification and returned through the query API operation.

    Note

    Because the video file is large, the system may discard it if the network is unstable to prioritize the transmission of essential verification images.

    N

    CallbackUrl

    String

    No

    The webhook address for verification result notifications. The callback request method is GET by default. The webhook address must start with https. After the verification is complete, the platform sends a callback to this address and automatically adds the following fields:

    • transactionId

    • passed

    • subcode

    Warning

    • The system checks whether this address is accessible before the API operation is called. If the address is not accessible over the public network, a 400 error is returned.

    • The callback is executed immediately after the verification is complete, but may be delayed due to network issues. We recommend that you first receive the verification completion notification on the client and then call the query API operation to obtain the verification details.

    https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

    CallbackToken

    String

    No

    A security token that you generate. It is used for anti-replay and tamper-proofing checks.

    If you set this parameter, the CallbackToken field is included in the CallbackUrl webhook.

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    No

    Specifies whether to enable strict face quality checks.

    • Y: Yes (default)

    • N: No

    Important

    • This configuration requires support from the client-side SDK. If you enable this feature, but the client-side SDK does not have the face quality detection module integrated, this configuration is treated as disabled.

    • The client-side SDK must be version 1.2.5 or later.

    N

    Returned data

    Name

    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

    Return to Code.

    Success

    Message

    String

    A detailed description of the return code.

    success

    Result.TransactionId

    String

    The unique identifier for the entire verification flow. This field is used for billing statistics and to initiate a CheckResult API operation request.

    Important

    • If an error occurs during the request, such as an invalid parameter, TransactionId is not returned.

    • Attach the TransactionId to the business ID of your current business flow and store it on the server-side. When calling CheckResult, retrieve this verification ID from your server-side storage to initiate the result query.

    • After you obtain the TransactionId or TransactionUrl, you must complete the verification within 30 minutes. After this period, the ID or URL will automatically become invalid and cannot be used for verification.

    hksb7ba1b28130d24e015d6********

    Result.Protocol

    String

    The standard encrypted protocol for verification.

    Obtain this parameter and pass it to the client SDK. The client SDK uses this parameter to reduce network interactions and support dynamic network switching to improve user experience.

    hksb7ba1b28130d24e015d*********

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