All Products
Search

This Product

    ID Verification:ID_OCR_MAX

    Document Center

    ID Verification:ID_OCR_MAX

    Last Updated:Dec 01, 2025

    ID_OCR_MAX is an ID Verification solution that uses the Qwen-VL large model to detect and recognize various types of ID certificates from around the world.

    Important

    In the Indonesia region, this API operation supports only the recognition of Indonesian ID cards (document type code IDN01001).

    Endpoint

    • API operation: DocOcrMax

    • Description: Uses the Qwen-VL large model to recognize the document type and extract information from an ID certificate image, and returns the relevant fields.

    • Request method: POST

    • Transport protocol: HTTPS

    • QPS limit: This API is subject to an exclusive queries per second (QPS) limit. For more information, see ID Verification server-side API QPS limits.

    • Endpoint:

      Note

      An internal network is a private communication network between Alibaba Cloud products in the same region. If your application server is deployed in an Alibaba Cloud region, you can use the internal endpoint to access the ID Verification service. This provides a more secure and stable network connection.

      Singapore

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

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

      Indonesia

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

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

    Online debugging and integration

    Note

    Before you debug and integrate, read the Use OpenAPI Explorer to debug and integrate server-side API operations document. It explains how to call API operations on the OpenAPI platform and how to obtain the SDK and its sample code.

    You can run this API operation 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, the uploaded image must meet all the following requirements:

    • Image format: JPG, JPEG, or PNG.

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

      Note

      When you pass parameters in base64 format, ensure that the original image size does not exceed 6 MB to stay within the 10 MB data transmission limit.

    • Image resolution: The image height and width must be between 200 pixels and 8192 pixels. The recommended resolution is 480 × 640 pixels (height × width).

    • Image quality recommendations:

      • The four corners of the ID card image must be complete. Avoid obstructing the document when holding it, because this can affect detection.

      • The content of the ID card image must be clear, unobstructed, and have no overexposed areas. The ID card image must not be tilted or inverted.

      • The ID card image should occupy more than 60% of the total image area. A smaller card area reduces the recognition accuracy.

      • We recommend using photos of real documents.

    Request parameters

    You can provide the image using one of the following two parameters:

    • IdOcrPictureBase64

    • IdOcrPictureUrl

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product solution to use. Set the value to ID_OCR_MAX.

    ID_OCR_MAX

    SceneCode

    String

    No

    A custom authentication scenario ID. You can use this ID to query related records in the console.

    It can be a combination of letters, digits, and underscores, up to 10 characters long.

    1234567890

    MerchantBizId

    String

    Yes

    A custom unique business ID. Use it to locate and troubleshoot issues later.

    It can be a combination of letters and digits, up to 32 characters long. Make sure that the ID is unique.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MerchantUserId

    String

    No

    A custom user ID or another identifier for a specific user, such as a mobile number or email address.

    Desensitize the value of this field in advance. For example, use hashing.

    123456789

    IdOcrPictureBase64

    String

    No

    The Base64-encoded image of the ID certificate.

    If you use IdOcrPictureBase64 to pass the ID certificate image, check the image size. Do not pass an oversized image.

    base64

    IdOcrPictureUrl

    String

    No

    The URL of the ID certificate image. The URL must be an HTTP or HTTPS link accessible over the public network.

    https://***.jpg

    OcrModel

    String

    No

    The optical character recognition (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

    Specifies whether to enable the document anti-spoofing feature:

    • T: Enable

    • F (default): Disable

    F

    IdThreshold

    String

    No

    The 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

    Specifies 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

    Specifies whether to enable verification with an authoritative data source to enhance document anti-spoofing capabilities.

    • T: Enable

    • F: Disable (default)

    Note

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

    • Data transfer declaration: If you enable this parameter, you agree to transfer the user's name and certificate number to an authoritative data source in the Chinese mainland for consistency verification.

    • Performance impact: After you enable this feature, the response time of the API operation increases by 1 to 2 seconds. Adjust the timeout setting.

    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.

      For information about the supported document types and pages, see Document types.

    • You can enable quality and anti-spoofing detection.

    This mode outputs detailed fields from the document page. For more information, see Document OCR fields.

    Recommended for online admission scenarios for ID Verification. This mode automatically verifies whether the document type is permitted for the business and outputs detailed fields from the document face.

    1: Automatic document classification mode

    Important

    This recognition mode is not supported in the Indonesia region.

    • You do not need to specify the document type.

    • Quality and anti-spoofing detection are not supported.

    This mode outputs only the detected document type code. For more information, see Global ID certificate codes.

    Recommended for offline business analysis scenarios. You can use this mode for clustering and cleansing of historical ID certificate images.

    2: Automatic document classification and general recognition mode

    Important

    This recognition mode is not supported in the Indonesia region.

    • You do not need to specify the document type.

    • Quality and anti-spoofing detection are not supported.

    This mode outputs the document type and key standardized fields from the document face. For more information, see the table of general recognition fields.

    Note

    This mode supports the output of only common fields across different document types.

    Recommended for offline scenarios that require assisted manual review. This mode recognizes the document type and key fields to improve review efficiency.

    Field standardization

    To handle the diversity of global ID certificates, ID Verification provides a field standardization feature. This feature supports standardized output formats for the following key document fields.

    Supported document types

    Note

    Currently, only the following three certificate types from South Korea are supported. Support for additional certificate types will be added based on demand.

    South Korea

    South Korean ID card

    KOR01001

    01

    South Korean driver's license

    KOR02001

    01

    South Korean passport

    KOR03001

    01

    Supported standardized fields

    Field

    Type

    Description

    surname_s

    String

    The surname in Latin letters.

    given_name_s

    String

    The given name in Latin letters.

    sex_s

    String

    The sex, F or M.

    date_of_birth_s

    String

    The date of birth in the yyyy-mm-dd format.

    date_of_expiry_s

    String

    The expiration date of the document in the yyyy-mm-dd format.

    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.

    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

    • If OcrModel is 0:

      {
  "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"
  }
}

    • If OcrModel is 1:

      {
  "ocrDocType":"CHN01"
}

    • If OcrModel is 2:

      {
  "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 information of 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 anti-counterfeiting detection, including the risk identification result and risk type:

    Note

    Card detection is enabled only when you set IdSpoof = Y in the Initialize operation.

    Otherwise, spoofResult returns N by default, and spoofType is empty.

    • spoofResult:

      • Y: Risk exists

      • N: Normal

    • spoofType:

      • SCREEN_REMARK: Recapture

      • PHOTO_COPY: Photocopy

      • TAMPER: Photoshop tampering

    {
 "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 information of 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"
}

    Return codes

    HTTP status code

    Code

    Message

    200

    Success

    Request successful.

    400

    MissingParameter

    Parameter cannot be empty.

    InvalidParameter

    Invalid parameter.

    401

    UnqualifiedPhoto

    The uploaded image is unreadable or the image resolution does not meet requirements. We recommend changing the image.

    Ensure the photo is clear, has normal exposure, is complete without occlusion, and has no significant angle deviation.

    DataDuplication

    Both Base64-encoded image and URL image address are provided. Choose only one of these parameters.

    ToolargeImage

    The image size is too large. We recommend compressing the image or changing the upload method.

    DownloadTimeout

    URL image download timeout.

    403

    Forbidden.RAMUserAccessDenied

    You need to grant the RAM user the AliyunAntCloudAuthFullAccess permission. For more information, see Authorize RAM users to access the service.

    Forbidden.AccountAccessDenied

    Ensure that you have activated ID verification and your account has no overdue payment.

    Throttling.Api

    API request is blocked due to throttling.

    500

    InternalError

    Internal system error. Provide feedback to engineers for troubleshooting.

    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.