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
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
project_id |
Yes |
String |
Project ID, which can be obtained by referring to Obtaining a Project ID. |
Request 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:
|
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:
NOTE:
|
alarm |
No |
Boolean |
Whether to enable the function to detect alarms for ID document images. The default value is false. The options are: |
Response Parameters
Status code: 200
Parameter |
Type |
Description |
---|---|---|
result |
Calling result of a successful API call. This parameter is not included when the call fails. |
Parameter |
Type |
Description |
---|---|---|
type |
String |
Document type. The options are:
|
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]. |
Parameter |
Type |
Description |
---|---|---|
detect_blur_result |
Boolean |
Whether the ID document in the image is blurry. The options are: |
detect_glare_result |
Boolean |
Whether the ID document in the image is reflective. The options are: |
detect_blocking_within_border_result |
Boolean |
Whether the ID document in the image is blocked within its borders. |
detect_insufficient_lighting_result |
Boolean |
Whether the ID document image is too dark. The options are: |
detect_copy_result |
Boolean |
Whether the ID document in the image is a black-and-white copy of the original. The options are: |
detect_border_integrity_result |
Boolean |
Whether the borders of the ID document in the image are incomplete. The options are: |
detect_reproduce_result |
Boolean |
Whether the ID document is recaptured. The options are: |
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
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.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot