All Products
Search

This Product

    ID Verification:ID_OCR_MAX

    Document Center

    ID Verification:ID_OCR_MAX

    Last Updated:Dec 24, 2025

    ID_OCR_MAX is an ID Verification solution powered by the Qwen-VL large model. It recognizes various types of ID certificates from around the world.

    Important

    In the Indonesia region, this operation recognizes only Indonesian ID cards and global passports (document type codes IDN01001 and GLB03002).

    Endpoints

    • API operation name: DocOcrMax

    • Description: This operation recognizes the document type and extracts information from an ID certificate image using the Qwen-VL large model. The operation then returns the relevant fields.

    • Request method: POST

    • Transport protocol: HTTPS

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

    • Endpoints:

      Note

      An internal network is the communication network between Alibaba Cloud products in the same region. If your business server is deployed in an Alibaba Cloud region, you can access the ID Verification service through an internal endpoint to ensure more secure and stable network communication.

      Singapore

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

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

      Indonesia

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

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

    Online testing and integration

    Note

    Before you start debugging and integration, make sure that you read the Use OpenAPI Explorer to debug and integrate server-side API operations document to understand how to call API operations on the OpenAPI platform and how to obtain the SDK and its sample code.

    You can test this operation directly in OpenAPI Explorer. You can also generate SDK code examples for this operation.

    Image format requirements

    To ensure stable model performance, make sure that the image you pass meets all the following conditions:

    • Image format: JPG, JPEG, PNG.

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

      Note

      Converting an image to base64 format increases the data size. If you pass parameters in base64 format, make sure that the original image size does not exceed 6 MB to avoid exceeding the 10 MB data transmission limit.

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

    • Image quality recommendations:

      • All four corners of the document image must be complete. Do not hold the document in a way that obstructs the view, because this can affect detection.

      • The content of the document image must be clear, unobstructed, and free of overexposure. The document image must be upright, not tilted or upside down.

      • The document image area should occupy more than 60% of the total image area. A smaller document image may affect recognition.

      • We recommend that you take photos of the actual document.

    Request parameters

    You can use one of the following two methods to pass the photo.

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

    The ID can be up to 10 characters long and can contain letters, digits, and underscores (_).

    1234567890

    MerchantBizId

    String

    Yes

    A custom unique business ID used to track and troubleshoot issues.

    The ID can be up to 32 characters long and can contain letters and digits. Make sure 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, hash the value.

    123456789

    IdOcrPictureBase64

    String

    No

    The base64 encoding of the certificate image.

    If you choose to pass the certificate photo using IdOcrPictureBase64, check the photo size. Do not pass an oversized photo.

    base64

    IdOcrPictureUrl

    String

    No

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

    https://***.jpg

    OcrModel

    String

    No

    The OCR recognition mode:

    Note

    Modes 1 and 2 do not support document quality detection 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 + general recognition mode

    0

    DocType

    String

    No

    Document type

    Note

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

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

    GLB03001

    DocPage

    String

    No

    The page to be recognized.

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

    • 02: The back side of the document.

    Important

    If the detected page 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 detection:

    • 0: System default

    • 1: Strict mode

    • 2: Loose mode

    • 3 (default): Disable quality detection

    3

    OcrValueStandard

    String

    No

    Specifies whether to return extra fields in a standardized OCR recognition format:

    • 0: No (default)

    • 1: Yes

    Note

    For information about 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 mainland resident ID cards (CHN01001) and Chinese mainland driver's licenses (CHN02001).

    • Data transfer declaration: 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 consistency verification.

    • Performance impact: Enabling this feature increases the API operation response time by about 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 a list of 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.

    This mode is recommended for online admission scenarios for ID Verification. It automatically verifies whether the document type is permitted for the business and outputs detailed fields from the card 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.

    • This mode does not support quality and anti-spoofing detection.

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

    This mode is recommended for offline business analysis scenarios. It is used for clustering and cleaning historical 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.

    • This mode does not support quality and anti-spoofing detection.

    This mode outputs the document type and key standardized fields from the card face. For more information, see General recognition fields.

    Note

    In this mode, only fields common to different documents are output.

    This mode is recommended for offline assisted manual review scenarios. It recognizes the card type and key fields to improve review efficiency.

    Field standardization

    To handle the diversity of global documents, ID Verification provides a field standardization feature. This feature outputs key document fields in a standardized format.

    Supported document types

    Note

    Currently, only the following three types of documents from South Korea are supported. Support for other document 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

    • OcrModel = 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"
  }
}

    • OcrModel = 1:

      {
  "ocrDocType":"CHN01"
}

    • OcrModel = 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 document OCR field information.

    Note

    If the document OCR process fails, this field is empty.

    {
  "expiryDate": "",
  "originOfIssue": "Exit and Entry Administration of the Ministry of Public Security",
  "englishName": "LI SI",
  "sex": "Male",
  "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 1 or 2.

    CHN01

    ocrStandardData

    String

    The standardized document OCR field information.

    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.