This topic describes how to call the asynchronous image detection API to recognize text from structured ID cards and other certificates using optical character recognition (OCR). The structured ID/card OCR feature recognizes text in certificate images and returns the content in a structured format. To use this feature, you must specify the type of certificate in the image.
Structured card and certificate OCR currently supports the following types of cards and certificates: business licenses, ID cards (portrait side and national emblem side), passports, bank cards, driver's licenses (front and back), vehicle licenses (front and back), license plates, vehicle VINs, household register head of household pages, and household register permanent resident pages.
Usage notes for asynchronous image detection
API operation: /green/image/asyncscan. This operation performs asynchronous image detection.
You can call this operation to create an asynchronous image detection task. For more information about how to construct an HTTP request, see Request structure. You can also use a pre-built HTTP request. For more information, see SDK overview.
Billing information:
You are charged for calling this operation. For more information about the billing methods, see
Detection timeout:
The maximum response time that is allowed for a synchronous moderation request is 6 seconds. If the moderation is not completed within 6 seconds, a timeout error is returned. If you do not require moderation results in real time, you can send asynchronous moderation requests. In most cases, we recommend that you send synchronous moderation requests because synchronous moderation operations are easier to call. We recommend that you set the timeout period to 6 seconds for calling synchronous moderation operations.
Return results:
If you send asynchronous moderation requests, the moderation results are not returned in real time. To obtain moderation results, you can poll the moderation results periodically or enable callback notification. The moderation results are retained for up to 1 hour.
Retrieve results using a callback: When you submit an asynchronous detection task, include the callback parameter in the request to receive the detection results automatically. For more information, see Asynchronous detection request parameters.
Retrieve results using polling: When you submit an asynchronous detection task, do not include the callback parameter. After you submit the task, call the result query operation to obtain the detection results. For more information, see Usage notes for querying asynchronous image detection results.
Image requirements:
The URLs of images must be HTTP or HTTPS URLs.
The images must be in PNG, JPG, JPEG, BMP, GIF, or WEBP format.
An image can be up to 20 MB in size. The limit for the image size is applicable to both synchronous and asynchronous moderation operations.
, The height or width cannot exceed30,000pixels (px), and the total pixels of the image cannot exceed2.5 hundred million (px)
Notewhere, GIFformat images, the total pixels of the image cannot exceed4,194,304(px), The height or width cannot exceed30,000pixels (px).
The duration for downloading an image is limited to 3 seconds. If an image fails to be downloaded within 3 seconds, a timeout error is returned.
We recommend that you submit images of at least 256 × 256 pixels to ensure the moderation effect.
The response time of an operation for moderating images varies based on the duration for downloading these images. Make sure that you use a stable and reliable storage service to store the images to be moderated. We recommend that you use Object Storage Service (OSS) or Content Delivery Network (CDN).
QPS limits
You can call this operation up to 10 times per second per account. If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation.
Asynchronous detection request parameters
Name | Type | Required | Example | Description |
bizType | String | No | default | The business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize moderation policies. |
scenes | StringArray | Yes | ["ocr"] | Specifies the detection scenario. Set the value to ocr. |
callback | String | No | http://www.aliyundoc.com/xx.json | The callback URL for notifying you of asynchronous moderation results. HTTP and HTTPS URLs are supported. If you do not set this parameter, you must poll moderation results periodically. If you set the callback parameter in the moderation request, make sure that the specified HTTP or HTTPS URL meets the following requirements: supports the POST method, uses UTF-8 to encode the transmitted data, and supports the checksum and content parameters. To send moderation results to the specified callback URL, Content Moderation returns the checksum and content parameters in callback notifications based on the following rules and format:
Note If your server successfully receives a callback notification, the server sends an HTTP 200 status code to Content Moderation. If your server fails to receive a callback notification, the server sends other HTTP status codes to Content Moderation. If your server fails to receive a callback notification, Content Moderation continues to push the callback notification until your server receives it. Content Moderation can push a callback notification repeatedly up to 16 times. After 16 times, Content Moderation stops pushing the callback notification. In this case, we recommend that you check the status of the callback URL. |
seed | String | No | aabbcc123 | A random string that is used to generate a signature for the callback notification request. The string can be up to 64 characters in length and can contain letters, digits, and underscores (_). You can customize this string. It is used to verify the callback notification request when Content Moderation pushes callback notifications to your server. Note This parameter is required if you set the callback parameter. |
cryptType | String | No | SHA256 | The encryption algorithm used to encrypt the callback notification content when you enable callback notification. AI Guardrails encrypts the returned string by using the encryption algorithm that you specify and sends the encrypted string to the callback URL. The returned string is in the UID + Seed + Content format. Valid values:
|
tasks | JSONArray | Yes | Specifies the detection objects. Each element in the JSON array is a struct for a detection task. You can specify up to 100 elements, which means you can submit up to 100 pieces of content for detection at a time. To support 100 elements, you must adjust the number of concurrent tasks to 100 or more. For more information about the structure of each element, see task. | |
extras | JSONObject | Yes | xxx | Specifies the type of certificate to recognize. The format is
|
Name | Type | Required | Example Value | Description |
dataId | String | No | test_data_xxxx | The data ID. Ensure that all IDs in a single request are unique. |
url | String | Yes | https://www.aliyundoc.com/test_image_xxxx.png | of the object to be detectedURL.
|
Asynchronous detection response parameters
Name | Type | Example value | Description |
code | Integer | 200 | The returned HTTP status code. For more information, see Common error codes. |
msg | String | OK | The response message for the request. |
dataId | String | The ID of the moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here. | |
taskId | String | img5A@k7a@B4q@6K@d9nfKgOs-1s**** | The ID of the detection task. |
url | String | https://www.aliyundoc.com/test_image_xxxx.png | of the object to be detectedURL.
|
extras | JSONObject | xxx | If you set the extras parameter in the moderation request, the value of the extras request parameter is returned here. Note This parameter may be subject to changes. Use the latest value of this parameter. |
Asynchronous detection examples
Request example
This example shows how to recognize a bank card by setting extras to {"card": "bank-card"}. To recognize other types of certificates, set the value to the corresponding certificate type. For more information, see Asynchronous detection request parameters.
http(s)://[Endpoint]/green/image/asyncscan
&<Common request parameters>
{
"scenes": [
"ocr"
],
"extras": {
"card": "bank-card"
},
"tasks": [
{
"dataId": "test_data_xxxx",
"url": "https://www.aliyundoc.com/test_image_xxxx.png"
}
]
}Successful response example
{
"code": 200,
"msg": "OK",
"requestId": "92AD868A-F5D2-4AEA-96D4-E1273B8E074C",
"data": [
{
"code": 200,
"msg": "OK",
"dataId": "test_data_xxxx",
"taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
"url": "https://www.aliyundoc.com/test_image_xxxx.png"
}
]
}Usage notes for querying asynchronous image detection results
API operation: /green/image/results. This operation queries the results of an asynchronous image detection task.
You can call this operation to query the results of an asynchronous image detection task. For more information about how to construct an HTTP request, see Request structure. You can also use a pre-built HTTP request. For more information, see SDK overview.
Billing information:
This operation is free of charge.
Query timeout:
We recommend that you query moderation results at least 30 seconds after you send an asynchronous moderation request. Content Moderation retains moderation results for up to 4 hours. After 4 hours, the results are deleted.
QPS limits
You can call this operation up to 10 times per second per account. If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation.
Result query request parameters
Name | Type | Required | Example value | Description |
body | JSONArray | Yes | ["img5A@k7a@B4q@6K@d9nfKgOs-1sWeLu"] | The list of IDs of asynchronous moderation tasks that you want to query. The array can contain up to 100 elements. After you submit a moderation task, you can obtain the ID of the task from the response. |
Result query response parameters
Name | Type | Example | Description |
code | Integer | 200 | The returned HTTP status code. For more information, see Common error codes. |
msg | String | OK | The response message for the request. |
dataId | String | test_data_xxxx | The ID of the moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here. |
taskId | String | img5A@k7a@B4q@6K@d9nfKgOs-1s**** | The ID of the detection task. |
url | String | https://www.aliyundoc.com/test_image_xxxx.png | of the object to be detectedURL.
|
extras | JSONObject | xxx | If you set the extras parameter in the moderation request, the value of the extras request parameter is returned here. Note This parameter may be subject to changes. Use the latest value of this parameter. |
results | Array | The returned results. When the call is successful (code=200), the response contains one or more elements. Each element is a struct. For more information about the structure, see result. |
Name | Type | Example | Description |
scene | String | ocr | The detection scenario. The value is ocr. |
label | String | ocr | The category of the detection result. Valid values:
|
suggestion | String | review | The recommended user action. Valid values:
|
rate | Float | 99.91 | In the OCR scenario, you can ignore this return value. |
businessLicenseInfo | Object | The recognized business license information. For more information about the structure, see businssLicenseInfo. Note This result is returned only when extras is set to | |
idCardInfo | Object | The recognized ID card information. For more information about the structure, see idCardInfo. Note This result is returned only when extras is set to | |
passportInfo | Object | The recognized passport information. For more information about the structure, see passportInfo. Note This result is returned only when extras is set to | |
bankCardInfo | Object | The recognized bank card information. For more information about the structure, see bankCardInfo. Note This result is returned only when extras is set to | |
driverLicenseFrontInfo | Object | The recognized information from the front of a driver's license. For more information about the structure, see driverLicenseFrontInfo. Note This result is returned only when extras is set to | |
driverLicenseBackInfo | Object | The recognized information from the back of a driver's license. For more information about the structure, see driverLicenseBackInfo. Note This result is returned only when extras is set to | |
vehicleLicenseFrontInfo | Object | The recognized information from the front of a vehicle license. For more information about the structure, see vehicleLicenseFrontInfo. Note This result is returned only when extras is set to | |
vehicleLicenseBackInfo | Object | The recognized information from the back of a vehicle license. For more information about the structure, see vehicleLicenseBackInfo. Note This result is returned only when extras is set to | |
vehicleNumInfo | Object | The recognized license plate information. For more information about the structure, see vehicleNumInfo. Note This result is returned only when extras is set to | |
vehicleVinInfo | Object | The recognized vehicle VIN information. For more information about the structure, see vehicleVinInfo. Note This result is returned only when extras is set to | |
ocrCardInfo | Object | The recognized OCR information from other certificates. For more information about the structure, see ocrCardInfo. Note This result is returned only when extras is set to one of the following values in the asynchronous detection request:
|
Name | Type | Example value | Description |
companyName | String | xxx Technology Co., Ltd. | The company name. |
companyType | String | Limited liability company | The company type. |
legalPerson | String | Zhang XX | The legal person. |
establishDate | String | January 01, 2000 | The registration date. |
vaildPeriod | String | January 01, 2030 | The business expiration date. |
address | String | xxx | The address. |
capital | String | xxx | The registered capital. |
business | String | Computer software and hardware development | The business scope. |
copy | Boolean | false | Specifies whether it is a replica. Valid values:
|
copyId | String | xxx | The copy number. |
certSN | String | xxx | The certificate number. |
creditCode | String | xxx | The Unified Social Credit Code. |
organizationCode | String | xxx | The organization code. |
taxCode | String | xxx | The tax registration number. |
companySN | String | xxx | The company number. |
composition | String | xxx | The composition form. |
paidInCapital | String | xxx | The paid-in capital. |
Name | Type | Sample value | Description |
name | String | Zhang XX | The name. |
nationality | String | Han | The nationality. |
number | String | 5****************9 | The ID card number. |
birth | String | 2022-01-01 | The date of birth. Format: YYYY-MM-DD. |
address | String | xxx | The address. |
authority | String | xxx | The issuing authority. |
startDate | String | 2022-06-30 | The start date of the validity period. Format: YYYY-MM-DD. |
endDate | String | 2032-06-30 | The end date of the validity period. Format: YYYY-MM-DD. Note This parameter may return the value Long-term. |
angle | Float | 96.2 | The clockwise rotation angle of the certificate. |
copy | Boolean | false | Indicates whether the ID card photo is a photocopy. Valid values:
Note This parameter is not returned by default. To have this parameter returned, contact your account manager. |
remake | Boolean | false | Indicates whether the ID card photo is a photo of a photo. Valid values:
Note This parameter is not returned by default. To have this parameter returned, contact your account manager. |
type | String | front | The certificate type. Valid values:
|
numberValid | Boolean | true | Indicates whether the certificate number is valid. Valid values:
|
Name | Type | Example | Description |
authority | String | xxx | The issuing authority. |
birthDate | String | January 01, 2020 | The date of birth. |
birthDay | String | January 01 | The birthday. |
birthPlace | String | xxx | The place of birth. |
birthPlaceRaw | String | xxx | The place of birth (in letters). |
expireDate | String | January 01, 2030 | The expiration date. |
expireDay | String | January 01 | The expiration day. |
issueDate | String | January 01, 2022 | The date of issue. |
issuePlace | String | xxx | The place of issue. |
issuePlaceRaw | String | xxx | The place of issue (in letters). |
name | String | Wang xx | The name. |
cnName | String | xxx | The Chinese name. |
cnNameRaw | String | xxx | The Chinese name (in letters). |
personId | String | 5****************9 | The identity ID. |
srcCountry | String | China | The nationality. |
type | String | xxx | The type. |
line0 | String | xxx | The first line at the bottom. |
line1 | String | xxx | The second line at the bottom. |
surname | String | Wang | The surname. |
givenName | String | xx | The given name. |
Name | Type | Example | Description |
bankCardNum | String | 622576888888**** | The bank card number. |
Name | Type | Example | Description |
name | String | Zhang XX | The name. |
number | String | 123xxxxxxxxxxxxxxxx | The driver's license number. |
address | String | No. xx, xx Street, xx District, xx City, xx Province | The address. |
vehicleType | String | C1 | The allowed vehicle type. |
validStartDate | String | 2022-01-01 | The start date of the validity period. Format: YYYY-MM-DD. |
validEndDate | String | 2028-01-01 | The end date of the validity period. Format: YYYY-MM-DD. |
Name | Type | Example | Description |
archiveNum | String | xxx | The archive number. |
Name | Type | Example | Description |
plateNum | String | Shaanxxxxxx | The license plate number. |
vehicleType | String | Small ordinary passenger car | The vehicle type. |
owner | String | Zhang XX | The owner's name. |
useCharacter | String | Non-commercial | The vehicle usage character. |
address | String | No. xx, xx Street, xx District, xx City, xx Province | The address. |
model | String | Dongfeng Nissan ABCxxxxx | The vehicle brand. |
vin | String | ABCxxxxxxxx1234 | The vehicle identification number. |
engineNum | String | 12xxxxA | The engine number. |
registerDate | String | 2022-01-01 | The registration date. Format: YYYY-MM-DD. |
issueDate | String | 2022-01-01 | The date of issue. Format: YYYY-MM-DD. |
Name | Type | Example value | Description |
plateNum | String | ShaanAxxxxx | The license plate number. |
fileNum | String | 12345678**** | The file number. |
appprovedPassengerCapacity | Integer | xxx | The approved passenger capacity. |
grossMass | String | xxx | The gross mass. |
unladenMass | String | xxx | The unladen mass. |
approvedLoad | String | xxx | The approved load. |
tractionMass | String | xxx | Gross Combination Weight Rating |
inspectionRecord | String | 1 | The inspection record. |
overallDimension | Object | The vehicle outline dimension information. For more information about the structure, see the following overallDimension table. |
Name | Type | Example | Description |
length | Integer | 4000 | The vehicle length, in millimeters. |
width | Integer | 2000 | The vehicle width, in millimeters. |
height | Integer | 1000 | The vehicle height, in millimeters. |
Name | Type | Example | Description |
num | String | ShaanAxxxxx | The license plate number. |
rate | Float | 99.01 | The confidence level of the license plate number. The value ranges from 0 to 100. A higher value indicates a higher confidence level. |
vehicleType | String | Small car | The license plate type. Valid values:
|
vehicleTypeRate | Float | 99.01 | The confidence level of the license plate type. The value ranges from 0 to 100. A higher value indicates a higher confidence level. |
Name | Type | Example value | Description |
vin | String | ABCxxxxxxxx1234 | The VIN. |
ocrCardInfo
Table 14. Household register head of household page information Name
Type
Example Value
Description
locationNumber
String
xxx
The lot number.
issueDate
String
January 01, 2022
The date of issue.
householdType
String
Resident household
The household type.
houseHolder
String
Zhang XX
The name of the head of household.
address
String
Guangxi xxx
The address.
community
String
xxx
The community of the head of household.
householdNumber
String
xxx
The household number.
undertaker
String
xxx
The seal of the undertaker.
type
String
household-head
The type of the card or certificate. The value is fixed at household-head, which indicates the head of household page of the household register.
Table 15. Household register permanent resident page information Name
Type
Example value
Description
occupation
String
Grain farmer
The occupation.
migrationDate1
String
January 01, 2022
When and from where the person moved to this address.
idNumber
String
5****************9
The ID card number.
education
String
Junior high school
The education level.
birthPlace
String
xxx
The place of birth.
servicePremises
String
xxx
The service premises.
householdNumber
String
xxx
The household number.
hometown
String
Chengdu, Sichuan
The hometown.
name
String
Zhang XX
The name.
formerName
String
xxx
The former name.
maritalStatus
String
Unmarried
The marital status.
nation
String
Han
Ethnic group.
otherAddress
String
xxx
Other address in this city.
birthday
String
January 01, 2020
The date of birth.
militaryService
String
xxx
The military service status.
relationTo
String
Head of household
The relationship to the head of household.
religion
String
xxx
The religious belief.
bloodType
String
B
The blood type.
registerDate
String
February 06, 2023
The registration date.
height
String
xxx
The height.
migrationDate2
String
Moved from xx County, xx Township, xx Village, xx
When and from where the person moved to this city.
undertaker
String
xxx
The seal of the undertaker.
type
String
household-resident
The type of the card or certificate. The value is fixed at household-resident, which indicates the permanent resident page of the household register.
Result query examples
Request example
http(s)://[Endpoint]/green/image/results
&<Common request parameters>
[
"img5A@k7a@B4q@6K@d9nfKgOs-1s****"
]Successful response examples
Bank card information
{ "code": 200, "data": [ { "code": 200, "dataId": "test_data_xxxx", "extras": { }, "msg": "OK", "results": [ { "bankCardInfo": { "bankCardNum": "622576888888****" }, "label": "ocr", "rate": 99.91, "scene": "ocr", "suggestion": "review" } ], "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****", "url": "https://www.aliyundoc.com/test_image_xxxx.png" } ], "msg": "success", "requestId": "1a2faf93-dd41-47d8-95ad-bdf6226540e4" }Household register (head of household page) information
{ "msg": "OK", "code": 200, "data": [ { "msg": "OK", "code": 200, "dataId": "test_data_xxxx", "extras": { }, "results": [ { "rate": 99.91, "suggestion": "review", "label": "ocr", "ocrCardInfo": { "houseHolder": "Resident household", "address": "Guangxi XXXXXX", "type": "household-head", "locationNumber": "", "issueDate": "Guangxi XXX", "community": "", "householdNumber": "", "householdType": "XXX", "undertaker": "Han" }, "scene": "ocr" } ], "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****", "url": "https://www.aliyundoc.com/test_image_xxxx.png" } ], "requestId": "6162F805-A6B9-446C-9B7C-5F26CFB03D89" }Household register (permanent resident page) information
{ "msg": "OK", "code": 200, "data": [ { "msg": "OK", "code": 200, "dataId": "test_data_xxxx", "extras": { }, "results": [ { "rate": 99.91, "suggestion": "review", "label": "ocr", "ocrCardInfo": { "birthday": "January 01, 2020", "hometown": "Sichuan Chengdu", "occupation": "Grain farmer", "education": "Junior high school", "nation": "Han", "militaryService": "", "relationTo": "Head of household", "type": "household-resident", "idNumber": "12345620200101****", "bloodType": "", "householdNumber": "", "religion": "", "undertaker": "XXX", "birthPlace": "XX Province XX", "migrationDate1": "ivzi.03.zoMoved from XX County, XX Township, XX Village XX", "migrationDate2": "", "otherAddress": "", "servicePremises": "", "name": "Zhi Xiaobao", "formerName": "", "maritalStatus": "", "registerDate": "February 06, 2023", "height": "" }, "scene": "ocr" } ], "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****", "url": "https://www.aliyundoc.com/test_image_xxxx.png" } ], "requestId": "AE11413F-1AE4-4147-8807-2F7673D67D72" }