All Products
Search

This Product

    ID Verification:ID_OCR_MAX.

    Document Center

    ID Verification:ID_OCR_MAX.

    Last Updated:Jun 25, 2026

    ID_OCR_MAX is an ID Verification solution that uses the Qwen-VL model to detect and recognize global ID certificates.

    Important

    Supported document types vary by region due to regional model limitations.

    • Singapore region: Supports the recognition of all document types listed in the Document types table.

    • Indonesia region: Supports only Indonesian ID cards and global passports (document type codes IDN01001 and GLB03002).

    • Malaysia region: Supports only Malaysian ID cards and global passports (document type codes MYS01001 and GLB03002).

    Endpoints

    • API operation: DocOcrMaxV2

    • Description: Recognizes the document type and extracts structured fields from an ID certificate image using the Qwen-VL large language model.

    • Request method: POST

    • Transport protocol: HTTPS

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

    • Service endpoint:

      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 network: cloudauth-intl.ap-southeast-3.aliyuncs.com

      • Internal network: cloudauth-intl-vpc.ap-southeast-3.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 run this API operation directly in OpenAPI Explorer to debug it. You can also generate SDK sample code for this API operation.

    Image format requirements

    To ensure stable model performance, upload images that meet all the following requirements:

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

    • Image size: The recommended size is 50 KB to 100 KB. The maximum size is 10 MB.

      Note

      Converting an image to base64 format typically increases the data size. If you pass the image as a base64-encoded string, ensure the original image size does not exceed 6 MB to stay within the 10 MB data transfer limit.

    • Image resolution: Image dimensions must be between 200 and 8,192 pixels. The recommended resolution is 480 × 640 (height × width).

    • Image quality recommendations:

      • Ensure that all four corners of the card image are visible. Avoid obstructing any part of the card, as this can affect detection.

      • Ensure the card image is clear, properly oriented, and free of obstructions or glare.

      • The card should occupy more than 60% of the total image area. If the card area is too small, recognition may be affected.

      • Use photos of the actual physical document.

    Request parameters

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product solution to use. Set to ID_OCR_MAX.

    ID_OCR_MAX

    SceneCode

    String

    No

    A custom scenario ID for querying related records in the console.

    Combination of letters, digits, and underscores, up to 10 characters.

    1234567890

    MerchantBizId

    String

    Yes

    A unique business ID for locating and troubleshooting issues.

    Combination of letters and digits, up to 32 characters. Must be unique.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MerchantUserId

    String

    No

    A custom user ID or identifier, such as a mobile phone number or email address.

    Desensitize this value before passing it (for example, by hashing).

    123456789

    IdOcrPictureBase64

    String

    No

    Note

    You can choose any one of the three upload methods.

    The Base64-encoded image of the ID certificate.

    When using IdOcrPictureBase64, ensure the image does not exceed the size limit.

    base64

    IdOcrPictureUrl

    String

    The publicly accessible HTTP or HTTPS URL of the ID certificate image.

    https://***.jpg

    IdOcrPictureFile

    InputStream

    ID document image file stream.

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

    OcrModel

    String

    No

    The OCR recognition mode:

    Note

    Modes 1 and 2 do not support document quality inspection or anti-spoofing detection. For more information, see Differences between recognition modes.

    • 0: Specified document recognition mode (default)

    • 1: Automatic document classification mode

    • 2: Automatic document classification and general recognition mode

    0

    DocType

    String

    No

    Document type

    Note

    • If OcrModel is set to 0, DocType is required. Specify the document type.

    • If OcrModel is set to 1 or 2, DocType must be empty.

    GLB03001

    DocPage

    String

    No

    The page to recognize.

    • 01 (default): The portrait side of the document.

    • 02: The back side of the document.

    Important

    If the page detected by the model does not match the specified page, Subcode 213 is returned.

    01

    IdSpoof

    String

    No

    Enables document anti-spoofing detection:

    • T: Enable

    • F (default): Disable

    F

    IdThreshold

    String

    No

    Custom threshold mode for OCR quality inspection:

    • 0: System default

    • 1: Strict mode

    • 2: Loose mode

    • 3 (default): Disable quality inspection

    3

    OcrValueStandard

    String

    No

    Whether to return additional OCR fields in a standardized format:

    • 0: No (default)

    • 1: Yes

    Note

    For information about the supported document types and standardized fields, see Field standardization.

    0

    Authorize

    String

    No

    Enables verification against an authoritative data source to strengthen anti-spoofing. Applies only when IdSpoof is enabled.

    • T: Enable

    • F: Disable (default)

    Note

    • Applicable certificate types: Chinese mainland resident ID cards (CHN01001) and Chinese mainland driver's licenses (CHN02001).

    • Data transmission statement: By enabling this parameter, you agree to transmit the user's name and certificate number to an authoritative data source in the Chinese mainland for a consistency check.

    • Performance impact: Enabling this parameter increases the API operation response time by about 1 to 2 seconds. Adjust the timeout setting.

    • Validation result: If this parameter is enabled and the information is inconsistent, the system returns authentication failure Subcode 212.

    T

    Differences between recognition modes

    OCR recognition mode

    Input differences

    Output differences

    Recommended scenarios

    0: Specified document recognition mode

    • You must specify the document type and page.

      Supported document types and pages are listed in Document types.

    • You can enable quality and anti-spoofing detection.

    Outputs detailed fields from the document page. See Document OCR fields for the full list.

    Best for online integration. Verifies the document type against your business configuration and outputs detailed fields.

    1: Automatic document classification mode

    Important

    This recognition mode is supported only in the Singapore region.

    • You do not need to specify the document type.

    • Quality and anti-spoofing detection are not supported.

    Outputs only the detected document type code. See Global ID certificate codes for details.

    Best for offline analysis. Use this mode to cluster and cleanse historical ID certificate images.

    2: Automatic document classification and general recognition mode

    Important

    This recognition mode is supported only in the Singapore region.

    • You do not need to specify the document type.

    • Quality and anti-spoofing detection are not supported.

    Outputs the document type and key standardized fields from the document face. See the table of general recognition fields.

    Note

    This mode outputs only the fields that are common to different document types.

    Best for offline manual review. Recognizes the document type and key fields to improve review efficiency.

    Response parameters

    Name

    Type

    Description

    Example

    HTTP Status Code

    Integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    String

    The request ID.

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

    Result.TransactionId

    String

    The unique ID for the entire authentication process.

    hksb7ba1b28130d24e015d694********

    Code

    String

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

    Success

    Message

    String

    A detailed description of the returned Code.

    success

    Result.Passed

    String

    Indicates whether the recognition is complete.

    Y

    Result.SubCode

    String

    Result description.

    200

    Result.ExtIdInfo

    String

    • OcrModel = 0:

      Example

      {
  "docType": "CHNPP01",
  "ocrIdInfo": {
    "passportNo": "E80358200",
    "expiryDate": "2026/06/05",
    "placeOfIssue": "GUANGDONG",
    "issuingAuthority": "MPS Exit & Entry Administration",
    "placeOfBirth": "HUBEI",
    "nationality": "Chinese",
    "surname": "YU",
    "givenname": "CAN",
    "countryCode": "CHN",
    "sex": "M",
    "birthDate": "1985/06/06"
  }
}

    • OcrModel = 1:

      Example

      {
  "ocrDocType":"CHN01"
}

    • OcrModel = 2:

      Example

      {
  "ocrDocType": "CHN01",
  "ocrIdInfo": {
     "given_name_s": "Jing",
     "surname_s": "Lu",
     "date_of_birth_s": "1976-05-23",
     "card_number_s": "642123197605230048",
     "sex_s": "F"
   }
}

    ExtIdInfo

    Name

    Type

    Description

    Example

    ocrIdInfo

    String

    The OCR field data extracted from the ID certificate.

    Note

    If the ID certificate OCR process fails, this field is empty.

    {
  "expiryDate": "",
  "originOfIssue": "MPS Exit & Entry Administration",
  "englishName": "LI SI",
  "sex": "M",
  "name": "Li Si",
  "idNumber": "H11111112",
  "issueDate": "2013-01-02",
  "birthDate": "1990-02-21"
}

    spoofInfo

    String

    The result of spoof detection, including the risk decision and risk types:

    Note

    Card spoofing detection is enabled only when IdSpoof = Y in the Initialize request.

    Otherwise, spoofResult defaults to N, and spoofType is empty.

    • spoofResult:

      • Y: Risk detected

      • N: Normal

    • spoofType:

      • SCREEN_REMARK: screen recapture

      • PHOTO_COPY: photocopy

      • TAMPER: tampering

      • SHORTCUT: screenshot

    {
 "spoofResult": "Y",
 "spoofType": ["SCREEN_REMARK"]
}

    ocrDocType

    String

    Document type code

    Note

    This field is returned only when OcrModel is set to 1 or 2.

    CHN01

    ocrStandardData

    String

    The standardized OCR field data extracted from the ID certificate.

    Note

    This field is returned only if the document type is supported and OcrValueStandard is set to 1.

    {
    "given_name_s": "HYUNEUI",
    "surname_s": "MUN",
    "date_of_expiry_s": "2028-02-08",
    "date_of_birth_s": "1988-10-26",
    "sex_s": "M"
}

    ResultObject.SubCode error codes

    Note

    Subcode is returned based on different product solutions or integration methods. For details, refer to the following table.

    Applicable solution

    Error code

    Is authentication record billed

    Description and suggested reasons

    General

    200

    Yes

    Authentication passed.

    • ID_OCR pure server-side integration (DocOcr)

    • ID_OCR_MAX

    211

    Yes

    The quality or resolution of the certificate image does not meet requirements, or the image itself is incomplete. Ensure the photo of the certificate's portrait side is clear, has normal exposure, is complete without occlusion, and has no significant angle deviation.

    • ID_OCR App (SDK) integration

    • ID_OCR Web (SDK) integration

    • ID_OCR_MAX

    212

    Yes

    Certificate anti-counterfeiting detection indicates risk. There may be high-risk operations such as rephotographing, tampering, or photocopying.

    • ID_OCR pure server-side integration (DocOcr)

    • ID_OCR_MAX

    213

    Yes

    The specified certificate type was not detected (recognition mode) or the certificate type could not be identified (classification mode).

    We recommend uploading a clear, complete certificate image with normal angle.