Call /green/image/scan to perform structured OCR on cards and certificates-AI Guardrails(AI Guardrails)-阿里云帮助中心

This topic describes how to call the synchronous image scan API to perform structured Optical Character Recognition (OCR) on cards and certificates. This feature recognizes text from images of cards and certificates and returns the content in a structured format. To use this feature, you must know the type of the card or certificate in the image that you want to scan.

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

API operation: /green/image/scan. This operation performs a synchronous image scan.

You can call this operation to create synchronous image scan tasks. 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.
Results:
In general, moderation results are returned within 1 second after you send a synchronous moderation request. The time may increase in special scenarios where a large number of requests are to be processed in the system, the size of images is large, or the images contain a large number of words. The speed of OCR is inversely relevant to the number of words in the images. If the images to be moderated contain a large number of words, we recommend that you send asynchronous moderation requests.
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)
  Note
  where, 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.

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.
tasks	JSONArray	Yes		Specifies the detection objects. Each element in the JSON array is a detection task struct. You can submit up to 100 elements at a time. To submit 100 elements, you must increase the number of concurrent tasks to 100 or more. For more information about the element structure, see task.
extras	JSONObject	Yes	{"card":"bank-card"}	Specifies the type of certificate to recognize. The format is `{"card":"${CardType}"}`. `CardType` specifies the certificate type. Valid values: business-license: business license id-card-front: ID card portrait side id-card-back: ID card national emblem side passport: passport bank-card: bank card driver-license-front: driver's license front driver-license-back: driver's license back vehicle-license-front: vehicle license front vehicle-license-back: vehicle license back vehicle-num: license plate vehicle-vin: vehicle VIN household-head: household register head of household page household-resident: household register permanent resident page

Table 1. task
Name	Type	Required	Example	Description
dataId	String	No	test_data_xxxx	The data ID. Make sure that all IDs in a request are unique.
url	String	Yes	https://aliyundoc.com/test_image_xxxx.png	of the object to be detectedURL. Public network HTTP/HTTPS URL, and the length cannot exceed2048 characters. Alibaba Cloud OSSthe file path provided.You must first authorize Content Moderation to accessOSSbucket, only in the same regionOSS bucket.For more information, seeauthorize Content Moderation to accessOSSbucket. file path format: oss://<bucket-name>.<endpoint>/<object-name>

Returned Data

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	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://aliyundoc.com/test_image_xxxx.png	of the object to be detectedURL. Public network HTTP/HTTPS URL, and the length cannot exceed2048 characters. Alibaba Cloud OSSthe file path provided.You must first authorize Content Moderation to accessOSSbucket, only in the same regionOSS bucket.For more information, seeauthorize Content Moderation to accessOSSbucket. file path format: oss://<bucket-name>.<endpoint>/<object-name>
extras	JSONObject	{"card":"bank-card"}	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 results. If the call is successful (code=200), the results contain one or more elements. Each element is a struct. For more information about the structure, see result.

Table 2. result
Name	Type	Example	Description
scene	String	ocr	The detection scenario. The value is ocr.
label	String	ocr	The classification of the detection result. Valid values: normal: No text is recognized in the image. ocr: The image contains text.
suggestion	String	review	The recommended user action. Valid values: pass: Ignores the return value. review: Review the recognized text.
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 businessLicenseInfo. Note This result is returned only if you set the extras request parameter to `{"card":"business-license"}`.
idCardInfo	Object		The recognized ID card information. For more information about the structure, see idCardInfo. Note This result is returned only if you set the extras request parameter to `{"card":"id-card-front"}` or `{"card":"id-card-back"}`.
passportInfo	Object		The recognized passport information. For more information about the structure, see passportInfo. Note This result is returned only if you set the extras request parameter to `{"card":"passport"}`.
bankCardInfo	Object		The recognized bank card information. For more information about the structure, see bankCardInfo. Note This result is returned only if you set the extras request parameter to `{"card":"bank-card"}`.
driverLicenseFrontInfo	Object		The recognized information on the front of the driver's license. For more information about the structure, see driverLicenseFrontInfo. Note This result is returned only if you set the extras request parameter to `{"card":"driver-license-front"}`.
driverLicenseBackInfo	Object		The recognized information on the back of the driver's license. For more information about the structure, see driverLicenseBackInfo. Note This result is returned only if you set the extras request parameter to `{"card":"driver-license-back"}`.
vehicleLicenseFrontInfo	Object		The recognized information on the front of the vehicle license. For more information about the structure, see vehicleLicenseFrontInfo. Note This result is returned only if you set the extras request parameter to `{"card":"vehicle-license-front"}`.
vehicleLicenseBackInfo	Object		The recognized information on the back of the vehicle license. For more information about the structure, see vehicleLicenseBackInfo. Note This result is returned only if you set the extras request parameter to `{"card":"vehicle-license-back"}`.
vehicleNumInfo	Object		The recognized license plate information. For more information about the structure, see vehicleNumInfo. Note This result is returned only if you set the extras request parameter to `{"card":"vehicle-num"}`.
vehicleVinInfo	Object		The recognized vehicle VIN information. For more information about the structure, see vehicleVinInfo. Note This result is returned only if you set the extras request parameter to `{"card":"vehicle-vin"}`.
ocrCardInfo	Object		The recognized OCR information of other cards and certificates. For more information about the structure, see ocrCardInfo. Note The corresponding result is returned only if you set the extras request parameter to one of the following values: `{"card":"household-head"}`: returns the information on the head of household page of the household register. `{"card":"household-resident"}`: returns the information on the permanent resident page of the household register.

Table 3. Business license information (businessLicenseInfo)
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: true: yes false: no
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.

Table 4. ID card information (idCardInfo)
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: true: yes false: no 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: true: yes false: no 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: front: ID card portrait side back: ID card national emblem side front_back: normal ID card with portrait and national emblem sides on the same page interim_front: temporary ID card portrait side interim_back: temporary ID card national emblem side interim_front_back: temporary ID card with portrait and national emblem sides on the same page
numberValid	Boolean	true	Indicates whether the certificate number is valid. Valid values: true: yes false: no Note If the length is incorrect or the number does not comply with national standards, false is returned.

Table 5. Passport information (passportInfo)
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.

Table 6. Bank card information (bankCardInfo)
Name	Type	Example	Description
bankCardNum	String	622576888888****	The bank card number.

Table 7. Driver's license front information (driverLicenseFrontInfo)
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.

Table 8. Driver's license back information (driverLicenseBackInfo)
Name	Type	Example	Description
archiveNum	String	xxx	The archive number.

Table 9. Vehicle license front information (vehicleLicenseFrontInfo)
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.

Table 10. Vehicle license back information (vehicleLicenseBackInfo)
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.

Table 11. overallDimension
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.

Table 12. License plate information (VehicleNumInfo)
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: Small car New energy vehicle Large car Trailer Coach car Police car Military vehicle Embassy or consulate vehicle Hong Kong or Macao vehicle
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.

Table 13. Vehicle VIN information (VehicleVinInfo)
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.

Examples

Request example

Note

The following example shows how to recognize a bank card (extras is set to {"card": "bank-card"}). To recognize other types of cards or certificates, set this parameter to the corresponding card or certificate type. For more information, see Request parameters.

http(s)://[Endpoint]/green/image/scan
&<Common request parameters>
{
    "scenes": [
        "ocr"
    ],
    "extras": {
        "card": "bank-card"
    },
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

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-1sWeLu",
            "url": "https://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": "img5EZCRaOpH8G4QFbNFLMf9p-1sWeKV",
            "url": "https://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": "Sikong Chengdu",
                        "occupation": "Grain farmer",
                        "education": "Junior high school",
                        "nation": "Han",
                        "militaryService": "",
                        "relationTo": "Head of household",
                        "type": "household-resident",
                        "idNumber": "5****************9",
                        "bloodType": "",
                        "householdNumber": "",
                        "religion": "",
                        "undertaker": "xxx",
                        "birthPlace": "xx Province xx",
                        "migrationDate1": "Moved from xx County, xx Township, xx Village, xx",
                        "migrationDate2": "",
                        "otherAddress": "",
                        "servicePremises": "",
                        "name": "xx",
                        "formerName": "",
                        "maritalStatus": "",
                        "registerDate": "February 06, 2023",
                        "height": ""
                    },
                    "scene": "ocr"
                }
            ],
            "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1sWeLu",
            "url": "https://aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "requestId": "AE11413F-1AE4-4147-8807-2F7673D67D72"
}