Help Center/ Optical Character Recognition/ API Reference/ API/ Auto ID Document Classification
Updated on 2025-07-02 GMT+08:00

Auto ID Document Classification

Function

This API classifies nine types of ID documents, detects alarms, and returns the results in JSON format. Supported document types include Peru ID card, Cambodian ID card, Hong Kong ID card, Macao ID card, Myanmar ID card, Myanmar driver's license, Thailand ID card, passport, and Chinese ID card.

Calling Method

For details, see Calling APIs.

URI

POST /v2/{project_id}/ocr/auto-id-doc-classification

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID, which can be obtained by referring to Obtaining a Project ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token.

Used to obtain the permission to call APIs. The token is the value of X-Subject-Token in the response header in Authentication.

Enterprise-Project-Id

No

String

Enterprise project ID. OCR allows you to use Enterprise Project Management Service (EPS) to split fees for resources used by different user groups and users.

To obtain the enterprise project ID, go to the Enterprise Project Management console, click the enterprise project name, and obtain the enterprise project ID on the enterprise project details page.

For how to create an enterprise project, see Optical Character Recognition User Guide.

NOTE:

Note:

After an enterprise project is created, parameter transfer involves the following scenarios:

  • If a correct enterprise project ID is carried and the OCR service can be used properly, the bills will be categorized under the corresponding enterprise project for that ID.

  • If an enterprise project ID that is in the correct format but does not actually exist is carried, and the OCR service can be used properly, the bills will display the corresponding non-existent enterprise project ID.

  • If no enterprise project ID or an enterprise project ID with incorrect format (such as special characters) is carried, and the OCR service can be used properly, the bills will be categorized under default.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

data

No

String

Set either this parameter or url.

Base64 encoded string of an image. The file size of a single image after Base64 encoding should not exceed 10 MB. Since files increase in size after Base64 encoding, it is recommended that the original image size not exceed 7 MB.

No side of the image can be smaller than 15 or larger than 8,192 pixels. Only images in JPEG, JPG, PNG, BMP, or TIFF format can be recognized.

An example is /9j/4AAQSkZJRgABAg.... If the image data contains an unnecessary prefix, the error "The image format is not supported" is reported.

url

No

String

Set either this parameter or data.

The file size of a single image after Base64 encoding should not exceed 10 MB. Since files increase in size after Base64 encoding, it is recommended that the original file size not exceed 7 MB.

No side of the image can be smaller than 15 or larger than 8,192 pixels. Only images in JPEG, JPG, PNG, BMP, or TIFF format can be recognized.

Image URL. Currently, the following URLs are supported:

  • Public HTTP/HTTPS URL

  • URL provided by OBS. You need to be authorized to use OBS data, including service authorization, temporary authorization, and anonymous public authorization. For details, see Configuring Access Permissions of OBS.

NOTE:
  • The API response time depends on the image download time. If the image download takes a long time, the API call will fail.

  • Ensure that the storage service where the image to be detected resides is stable and reliable. OBS is recommended for storing image data.

  • The URL cannot contain Chinese characters. If Chinese characters exist, they must be encoded using UTF-8.

alarm

No

Boolean

Whether to enable the function to detect alarms for ID document images. The default value is false. The options are:

  • true: Enable the image alarm function.

  • false: Disable the image alarm function.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

result

AutoIdDocClassificationResult object

Calling result of a successful API call.

This parameter is not included when the call fails.

Table 5 AutoIdDocClassificationResult

Parameter

Type

Description

type

String

Document type. The options are:

  • peru_id_card: Peruvian ID card
  • cambodian_id_card: Cambodian ID card
  • hongkong_id_card: Hong Kong (China) ID card
  • macao_id_card: Macao (China) ID card
  • myanmar_driver_license: Myanmar driver's license
  • myanmar_id_card: Myanmar ID card
  • passport: passport
  • thailand_id_card: Thailand ID card
  • id_card: Chinese ID card

location

Array<Array<Integer>>

Position of the ID document.

confidence

Float

Confidence of the ID document's position.

alarm_result

Object

Image alarm detection result.

This parameter is returned only when alarm is set to true. For details about the fields, see Table 6.

detect_blur_result, detect_glare_result, detect_blocking_within_border_result, detect_insufficient_lighting_result, detect_copy_result, detect_border_integrity_result, and detect_reproduce_result

alarm_confidence

Object

Score of the image alarm detection result.

This parameter is returned only when alarm is set to true. The fields below are included. For details about the fields, see Table 7.

blur_score, glare_score, blocking_within_border_score, insufficient_lighting_score, copy_score, border_integrity_score, and reproduce_score. The value range of these fields is [0, 99].

Table 6 AutoIdDocClassificationAlarmResult

Parameter

Type

Description

detect_blur_result

Boolean

Whether the ID document in the image is blurry. The options are:

  • true: The ID document image is blurry.

  • false: The ID document image is clear.

detect_glare_result

Boolean

Whether the ID document in the image is reflective. The options are:

  • true: The ID document image is blurry.

  • false: The ID document image is clear.

detect_blocking_within_border_result

Boolean

Whether the ID document in the image is blocked within its borders.

  • true: The ID document image is blurry.

  • false: The ID document image is clear.

detect_insufficient_lighting_result

Boolean

Whether the ID document image is too dark. The options are:

  • true: The ID document image is blurry.

  • false: The ID document image is clear.

detect_copy_result

Boolean

Whether the ID document in the image is a black-and-white copy of the original. The options are:

  • true: The ID document is a copy.

  • false: The ID document is the original.

detect_border_integrity_result

Boolean

Whether the borders of the ID document in the image are incomplete. The options are:

  • true: The borders are incomplete.

  • false: The borders are complete.

detect_reproduce_result

Boolean

Whether the ID document is recaptured. The options are:

  • true: The ID document is recaptured.

  • false: The ID document is not recaptured.

Table 7 AutoIdDocClassificationAlarmConfidence

Parameter

Type

Description

blur_score

Integer

Alarm score for whether the ID document image is blurry. The higher the score, the more likely it is that the ID document image is blurry.

glare_score

Integer

Alarm score for whether the ID document image is reflective. The higher the score, the more likely it is that the ID document image is reflective.

blocking_within_border_score

Integer

Alarm score for whether the ID document is blocked within its borders. The higher the score, the more likely it is that the ID document is blocked within its borders.

insufficient_lighting_score

Integer

Alarm score for whether the ID document image is too dark. The higher the score, the more likely it is that the ID document image is too dark.

copy_score

Integer

Alarm score for whether the ID document in the image is a copy of the original. The higher the score, the more likely it is that the ID document is a copy.

border_integrity_score

Integer

Alarm score for whether ID document borders are incomplete. The higher the score, the more likely it is that the ID document borders are incomplete.

reproduce_score

Integer

Alarm score for whether the ID document in the image is recaptured. The higher the score, the more likely it is that the ID document is recaptured.

Status code: 400

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Error code when the API call fails. For details, see "Error Codes".

This parameter is not included for a successful call.

error_msg

String

Error message when the API call fails.

This parameter is not included for a successful call.

Example Request

  • Transfer the Base64 encoded string of the auto ID document classification image for recognition.

    POST https://{endpoint}/v2/{project_id}/ocr/auto-id-doc-classification
    
    {
      "data" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...",
      "alarm" : true
    }
  • Transfer the URL of the auto ID document classification image for recognition.

    POST https://{endpoint}/v2/{project_id}/ocr/auto-id-doc-classification
    
    {
      "url" : "https://BucketName.obs.myhuaweicloud.com/ObjectName",
      "alarm" : true
    }

Example Response

Status code: 200

Example response for a successful request

{
  "result" : {
    "type" : "id_card",
    "location" : [ [ 275, 125 ], [ 860, 165 ], [ 916, 634 ], [ 255, 633 ] ],
    "confidence" : 0.979,
    "alarm_result" : {
      "detect_blur_result" : true,
      "detect_glare_result" : false,
      "detect_blocking_within_border_result" : false,
      "detect_insufficient_lighting_result" : false,
      "detect_copy_result" : false,
      "detect_border_integrity_result" : false,
      "detect_reproduce_result" : false
    },
    "alarm_confidence" : {
      "blur_score" : 98,
      "glare_score" : 0,
      "blocking_within_border_score" : 0,
      "insufficient_lighting_score" : 0,
      "copy_score" : 0,
      "border_integrity_score" : 0,
      "reproduce_score" : 0
    }
  }
}

Status code: 400

Example response for a failed request

{
  "error_code" : "AIS.0103",
  "error_msg" : "The image size does not meet the requirements."
}

Example SDK Code

The example SDK code is as follows:

  • Transfer the Base64 encoded string of the auto ID document classification image for recognition.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    package com.huaweicloud.sdk.test;
    
    import com.huaweicloud.sdk.core.auth.ICredential;
    import com.huaweicloud.sdk.core.auth.BasicCredentials;
    import com.huaweicloud.sdk.core.exception.ConnectionException;
    import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
    import com.huaweicloud.sdk.core.exception.ServiceResponseException;
    import com.huaweicloud.sdk.ocr.v1.region.OcrRegion;
    import com.huaweicloud.sdk.ocr.v1.*;
    import com.huaweicloud.sdk.ocr.v1.model.*;
    
    
    public class RecognizeAutoIdDocClassificationSolution {
    
        public static void main(String[] args) {
            // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
            // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
            String ak = System.getenv("CLOUD_SDK_AK");
            String sk = System.getenv("CLOUD_SDK_SK");
            String projectId = "{project_id}";
    
            ICredential auth = new BasicCredentials()
                    .withProjectId(projectId)
                    .withAk(ak)
                    .withSk(sk);
    
            OcrClient client = OcrClient.newBuilder()
                    .withCredential(auth)
                    .withRegion(OcrRegion.valueOf("<YOUR REGION>"))
                    .build();
            RecognizeAutoIdDocClassificationRequest request = new RecognizeAutoIdDocClassificationRequest();
            AutoIdDocClassificationRequestBody body = new AutoIdDocClassificationRequestBody();
            body.withAlarm(true);
            body.withData("/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...");
            request.withBody(body);
            try {
                RecognizeAutoIdDocClassificationResponse response = client.recognizeAutoIdDocClassification(request);
                System.out.println(response.toString());
            } catch (ConnectionException e) {
                e.printStackTrace();
            } catch (RequestTimeoutException e) {
                e.printStackTrace();
            } catch (ServiceResponseException e) {
                e.printStackTrace();
                System.out.println(e.getHttpStatusCode());
                System.out.println(e.getRequestId());
                System.out.println(e.getErrorCode());
                System.out.println(e.getErrorMsg());
            }
        }
    }
    
  • Transfer the URL of the auto ID document classification image for recognition.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    package com.huaweicloud.sdk.test;
    
    import com.huaweicloud.sdk.core.auth.ICredential;
    import com.huaweicloud.sdk.core.auth.BasicCredentials;
    import com.huaweicloud.sdk.core.exception.ConnectionException;
    import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
    import com.huaweicloud.sdk.core.exception.ServiceResponseException;
    import com.huaweicloud.sdk.ocr.v1.region.OcrRegion;
    import com.huaweicloud.sdk.ocr.v1.*;
    import com.huaweicloud.sdk.ocr.v1.model.*;
    
    
    public class RecognizeAutoIdDocClassificationSolution {
    
        public static void main(String[] args) {
            // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
            // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
            String ak = System.getenv("CLOUD_SDK_AK");
            String sk = System.getenv("CLOUD_SDK_SK");
            String projectId = "{project_id}";
    
            ICredential auth = new BasicCredentials()
                    .withProjectId(projectId)
                    .withAk(ak)
                    .withSk(sk);
    
            OcrClient client = OcrClient.newBuilder()
                    .withCredential(auth)
                    .withRegion(OcrRegion.valueOf("<YOUR REGION>"))
                    .build();
            RecognizeAutoIdDocClassificationRequest request = new RecognizeAutoIdDocClassificationRequest();
            AutoIdDocClassificationRequestBody body = new AutoIdDocClassificationRequestBody();
            body.withAlarm(true);
            body.withUrl("https://BucketName.obs.myhuaweicloud.com/ObjectName");
            request.withBody(body);
            try {
                RecognizeAutoIdDocClassificationResponse response = client.recognizeAutoIdDocClassification(request);
                System.out.println(response.toString());
            } catch (ConnectionException e) {
                e.printStackTrace();
            } catch (RequestTimeoutException e) {
                e.printStackTrace();
            } catch (ServiceResponseException e) {
                e.printStackTrace();
                System.out.println(e.getHttpStatusCode());
                System.out.println(e.getRequestId());
                System.out.println(e.getErrorCode());
                System.out.println(e.getErrorMsg());
            }
        }
    }
    
  • Transfer the Base64 encoded string of the auto ID document classification image for recognition.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    # coding: utf-8
    
    import os
    from huaweicloudsdkcore.auth.credentials import BasicCredentials
    from huaweicloudsdkocr.v1.region.ocr_region import OcrRegion
    from huaweicloudsdkcore.exceptions import exceptions
    from huaweicloudsdkocr.v1 import *
    
    if __name__ == "__main__":
        # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak = os.environ["CLOUD_SDK_AK"]
        sk = os.environ["CLOUD_SDK_SK"]
        projectId = "{project_id}"
    
        credentials = BasicCredentials(ak, sk, projectId)
    
        client = OcrClient.new_builder() \
            .with_credentials(credentials) \
            .with_region(OcrRegion.value_of("<YOUR REGION>")) \
            .build()
    
        try:
            request = RecognizeAutoIdDocClassificationRequest()
            request.body = AutoIdDocClassificationRequestBody(
                alarm=True,
                data="/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA..."
            )
            response = client.recognize_auto_id_doc_classification(request)
            print(response)
        except exceptions.ClientRequestException as e:
            print(e.status_code)
            print(e.request_id)
            print(e.error_code)
            print(e.error_msg)
    
  • Transfer the URL of the auto ID document classification image for recognition.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    # coding: utf-8
    
    import os
    from huaweicloudsdkcore.auth.credentials import BasicCredentials
    from huaweicloudsdkocr.v1.region.ocr_region import OcrRegion
    from huaweicloudsdkcore.exceptions import exceptions
    from huaweicloudsdkocr.v1 import *
    
    if __name__ == "__main__":
        # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak = os.environ["CLOUD_SDK_AK"]
        sk = os.environ["CLOUD_SDK_SK"]
        projectId = "{project_id}"
    
        credentials = BasicCredentials(ak, sk, projectId)
    
        client = OcrClient.new_builder() \
            .with_credentials(credentials) \
            .with_region(OcrRegion.value_of("<YOUR REGION>")) \
            .build()
    
        try:
            request = RecognizeAutoIdDocClassificationRequest()
            request.body = AutoIdDocClassificationRequestBody(
                alarm=True,
                url="https://BucketName.obs.myhuaweicloud.com/ObjectName"
            )
            response = client.recognize_auto_id_doc_classification(request)
            print(response)
        except exceptions.ClientRequestException as e:
            print(e.status_code)
            print(e.request_id)
            print(e.error_code)
            print(e.error_msg)
    
  • Transfer the Base64 encoded string of the auto ID document classification image for recognition.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    package main
    
    import (
    	"fmt"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
        ocr "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1/model"
        region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1/region"
    )
    
    func main() {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak := os.Getenv("CLOUD_SDK_AK")
        sk := os.Getenv("CLOUD_SDK_SK")
        projectId := "{project_id}"
    
        auth := basic.NewCredentialsBuilder().
            WithAk(ak).
            WithSk(sk).
            WithProjectId(projectId).
            Build()
    
        client := ocr.NewOcrClient(
            ocr.OcrClientBuilder().
                WithRegion(region.ValueOf("<YOUR REGION>")).
                WithCredential(auth).
                Build())
    
        request := &model.RecognizeAutoIdDocClassificationRequest{}
    	alarmAutoIdDocClassificationRequestBody:= true
    	dataAutoIdDocClassificationRequestBody:= "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA..."
    	request.Body = &model.AutoIdDocClassificationRequestBody{
    		Alarm: &alarmAutoIdDocClassificationRequestBody,
    		Data: &dataAutoIdDocClassificationRequestBody,
    	}
    	response, err := client.RecognizeAutoIdDocClassification(request)
    	if err == nil {
            fmt.Printf("%+v\n", response)
        } else {
            fmt.Println(err)
        }
    }
    
  • Transfer the URL of the auto ID document classification image for recognition.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    package main
    
    import (
    	"fmt"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
        ocr "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1/model"
        region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1/region"
    )
    
    func main() {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak := os.Getenv("CLOUD_SDK_AK")
        sk := os.Getenv("CLOUD_SDK_SK")
        projectId := "{project_id}"
    
        auth := basic.NewCredentialsBuilder().
            WithAk(ak).
            WithSk(sk).
            WithProjectId(projectId).
            Build()
    
        client := ocr.NewOcrClient(
            ocr.OcrClientBuilder().
                WithRegion(region.ValueOf("<YOUR REGION>")).
                WithCredential(auth).
                Build())
    
        request := &model.RecognizeAutoIdDocClassificationRequest{}
    	alarmAutoIdDocClassificationRequestBody:= true
    	urlAutoIdDocClassificationRequestBody:= "https://BucketName.obs.myhuaweicloud.com/ObjectName"
    	request.Body = &model.AutoIdDocClassificationRequestBody{
    		Alarm: &alarmAutoIdDocClassificationRequestBody,
    		Url: &urlAutoIdDocClassificationRequestBody,
    	}
    	response, err := client.RecognizeAutoIdDocClassification(request)
    	if err == nil {
            fmt.Printf("%+v\n", response)
        } else {
            fmt.Println(err)
        }
    }
    

For more SDK code examples in various programming languages, see the Sample Code tab on the right of the API Explorer page, which can automatically generate corresponding SDK code examples.

Status Codes

Status Code

Description

200

Example response for a successful request

400

Example response for a failed request

See Status Codes.

Error Codes

See Error Codes.