This topic describes how to use the synchronous image detection API to recognize structured receipts with Optical Character Recognition (OCR). The API recognizes text in receipt images and returns the text content in a structured format. Before you use this feature, you must know the type of receipt in the image.
This feature supports the following receipt types: VAT invoices, quota invoices, train tickets, and taxi receipts.
Usage notes
API endpoint: /green/image/scan. This API performs synchronous image detection.
You can call this API to create a synchronous image detection task. For information about how to construct an HTTP request, see Request structure. You can also use a pre-constructed 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
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.
，高度或者宽度不能超过30,000像素（px），且图像总像素不超过2.5亿（px）
Note其中，GIF格式的图片，图像总像素不超过4,194,304（px），高度或者宽度不能超过30,000像素（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 内容安全控制台. For more information, see Customize policies for machine-assisted moderation. |
| scenes | StringArray | Yes | ["ocr"] | The detection scenario. Set the value to ocr. |
| tasks | JSONArray | Yes | The detection objects. Each element in the JSON array is a detection task struct. You can submit up to 100 tasks in a single request. To submit 100 tasks, you must set the number of concurrent tasks to more than 100. For more information about the structure of each element, see task. | |
| extras | JSONObject | Yes | {"card":"invoice"} | The type of receipt to recognize. The format is {"card":"${CardType}"}. CardType is the receipt type. Valid values:
|
| Name | Type | Required | Example | Description |
| dataId | String | No | test_data_xxxx | The data ID. All IDs in a request must be unique. |
| url | String | Yes | https://aliyundoc.com/test_image_xxxx.png | The URL of the image to detect. |
Response data
| 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 | img1CVBf$Vgrno7wF75H5LaRm-1pP**** | The ID of the detection task. |
| url | String | https://aliyundoc.com/test_image_xxxx.png | The URL of the detection object. |
| extras | JSONObject | {"card":"invoice"} | 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. If the call is successful (code=200), the results contain one or more elements. Each element is a struct. For a description of the structure, see 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:
|
| suggestion | String | review | The recommended user action. Valid values:
|
| rate | Float | 99.91 | In the OCR scenario, you can ignore this return value. |
| invoiceInfo | Object | The recognized VAT invoice information. For a description of the structure, see invoiceInfo. Note This parameter is returned only when you set extras to {"card":"invoice"} in the request. | |
| ocrCardInfo | Object | The OCR information of other recognized receipts. For a description of the structure, see ocrCardInfo. Note This parameter is returned only when you specify one of the following values for extras in the request:
|
| Name | Type | Example | Description |
| invoice_name | String | **VAT Special Invoice | Invoice name. |
| invoice_id | Integer | 110015**** | Invoice code. |
| invoice_number | Integer | 5795**** | Invoice number. |
| invoice_date | Integer | 20170422 | Invoice date. |
| invoice_bcompany | String | **** Software Co., Ltd. | Purchaser name. |
| invoice_bcode | String | 91330000000000**** | Purchaser's taxpayer identification number. |
| invoice_baddress | String | **** | Purchaser's address and phone number. |
| invoice_baccount | String | ** Bank, a certain branch **** | Purchaser's bank and account number. |
| invoice_password | String | 1<000+0000-0000>79*27<>7295<-123020-8>07+63*683-80+>314-9+0+/<0-<-/1++35*958*6>98709/+9323858+8745<72461**** | Invoice password. |
| invoice_detail | Array | Invoice details. | |
| invoice_totalamount | Float | 4222.22 | Total amount. |
| invoice_totaltax | Float | 717.78 | Total tax. |
| invoice_totalamountupper | String | Four Thousand Nine Hundred and Forty Yuan Only | Total price and tax (in words). |
| invoice_totalamountlower | String | 4940.00 | Total price and tax (in figures). |
| invoice_scompany | String | **** Co., Ltd. | Seller name. |
| invoice_scode | String | 91110000000000**** | Seller's taxpayer identification number. |
| invoice_saddress | String | **** | Seller's address and phone number. |
| invoice_saccount | String | **** Branch 1105011012340000**** | Seller's bank and account number. |
| invoice_remark | String | KP12**** | Remarks. |
| invoice_payee | String | xxx | Payee. |
| invoice_reviewer | String | xxx | Review |
| invoice_drawer | String | Ms. Zhang | Drawer. |
| Name | Type | Example | Description |
| detail_name | String | Rongli Longya Flower Tea | Name of goods or taxable services. |
| detail_type | String | xxx | Specifications. |
| detail_unit | String | xxx | Unit. |
| detail_count | Float | 20 | Quantity. |
| detail_unitprice | Float | 44.4444444 | Unit price. |
| detail_amount | Float | 888.89 | Amount. |
| detail_rate | String | 17% | Tax rate. |
| detail_tax | Float | 151.11 | Tax amount. |
Table 5. Quota invoice information Name Type Example Description amountInWords String One Hundred Yuan Amount in words. invoiceSerial String Parsed invoice code. amountInFigures String 100 Amount in figures. invoiceNumber String 0145**** Invoice number. invoiceCode String 15113159**** Invoice code. batchNumber String 01 Batch number. year String 2015 Year. taxBureauCode String National Tax Tax bureau code. invoiceIndustryCode String None Invoice industry code. amountVersion String Computerized version Amount version. regionalismCode String Nanchong City Administrative region code. invoiceCategoryCode String Invoice Exchange Voucher Invoice category code. type String quota-invoice The type of the receipt. The value is fixed at quota-invoice, which indicates a quota invoice. Table 6. Train ticket information Name Type Example Description price String 0.0 Price. ticketNumber String A000001 Ticket number. departureTime String Departs at 00:00 on January 01, 2019 Departure time. seatType String Second Class Seat Seat type. trainNumber String G0000 Train number. departure String Origin Station Departure station. departurePhonics String Shifa Departure station (Pinyin). seatNumber String Car 01, Seat 01F Seat number. destination String Destination Station Arrival station. destinationPhonics String Zhongdao Arrival station (Pinyin). passengerInfo String 1234567890****0000Name Passenger information. type String train-ticket The type of the receipt. The value is fixed at train-ticket, which indicates a train ticket. Table 7. Taxi receipt information Name Type Example Description actualCollection String 100 Amount received. carNumber String A•T**** License plate number. date String September 16, 2008 Date. invoiceCode String 25000071**** Invoice code. invoiceNumbe String 5485G0**** Invoice number. mileage String 42.0km Mileage. amount String 100 Amount. getOffTime String 16:58 Drop-off time. boardingTime String [K068016:50 Pick-up time. totalAmount String 100 Total. type String taxi-ticket The type of the receipt. The value is fixed at taxi-ticket, which indicates a taxi receipt.
Examples
extras is set to {"card": "invoice"}). To recognize other types of receipts, set `extras` to the corresponding receipt type. For more information, see Request parameters.http(s)://[Endpoint]/green/image/scan
&<Common request parameters>
{
"scenes": [
"ocr"
],
"extras": {
"card": "invoice"
},
"tasks": [
{
"dataId": "test_data_xxxx",
"url": "https://aliyundoc.com/test_image_xxxx.png"
}
]
}- VAT invoice information
{ "msg":"OK", "code":200, "data":[ { "msg":"OK", "code":200, "dataId":"test_data_xxxx", "extras":{ "md5":"303f7159179153a94033724ffd28ea44" }, "results":[ { "invoiceInfo":{ "invoice_bcompany":"**** Software Co., Ltd.", "invoice_baccount":"** Bank, a certain branch ****", "invoice_drawer":"Ms. Zhang", "invoice_totalamountupper":"Four Thousand Nine Hundred and Forty Yuan Only", "invoice_name":"** VAT Special Invoice", "invoice_date":"20170422", "invoice_totaltax":"717.78", "invoice_reviewer":"", "invoice_totalamountlower":"4940.00", "invoice_id":"110015****", "invoice_number":"5795****", "invoice_scompany":"**** Co., Ltd.", "invoice_saccount":"**** Branch 1105011012340000****", "invoice_saddress":"****", "invoice_remark":"KP12****", "invoice_totalamount":"4222.22", "invoice_password":"1<000+0000-0000>79*27<>7295<-123020-8>07+63*683-80+>314-9+0+/<0-<-/1++35*958*6>98709/+9323858+8745<72461****", "invoice_payee":"", "invoice_detail":[ { "detail_amount":"888.89", "detail_name":"Rongli Longya Flower Tea", "detail_rate":"17%", "detail_count":"20", "detail_type":"", "detail_unitprice":"44.4444444", "detail_tax":"151.11", "detail_unit":"" }, { "detail_amount":"3333.33", "detail_name":"Dafo Longjing Green Tea", "detail_rate":"17%", "detail_count":"50", "detail_type":"", "detail_unitprice":"66.6666667", "detail_tax":"566.67", "detail_unit":"" } ], "invoice_baddress":"****", "invoice_bcode":"91330000000000****", "invoice_scode":"91110000000000****" }, "rate":99.91, "suggestion":"review", "label":"ocr", "scene":"ocr" } ], "taskId":"img1CVBf$Vgrno7wF75H5LaRm-1p****", "url":"https://aliyundoc.com/test_image_xxxx.png" } ], "requestId":"81121B0B-2BFE-44BA-9825-C15CA5E99551" } - Train ticket information
{ "msg": "OK", "code": 200, "data": [ { "msg": "OK", "code": 200, "dataId": "test_data_xxxx", "extras": { }, "results": [ { "rate": 99.91, "suggestion": "review", "label": "ocr", "ocrCardInfo": { "departureTime": "Departs at 00:00 on January 01, 2019", "ticketNumber": "A000001", "seatType": "Second Class Seat", "price": "0.0", "destination": "Destination Station", "passengerInfo": "1234567890****0000Name", "trainNumber": "G0000", "departure": "Origin Station", "destinationPhonics": "Zhongdao", "type": "train-ticket", "seatNumber": "Car 01, Seat 01F", "departurePhonics": "Shifa" }, "scene": "ocr" } ], "taskId": "img5ubtZeVSXxd7010wn9mHhd-1s****", "url": "https://aliyundoc.com/test_image_xxxx.png" } ], "requestId": "C55D1390-B1D0-4B27-83F3-7335006525E2" } - Quota invoice information
{ "msg": "OK", "code": 200, "data": [ { "msg": "OK", "code": 200, "dataId": "test_data_xxxx", "extras": { }, "results": [ { "rate": 99.91, "suggestion": "review", "label": "ocr", "ocrCardInfo": { "amountInWords": "One Hundred Yuan", "amountInFigures": "", "invoiceSerial": { "amountVersion": "Computerized version", "year": "2015", "invoiceCategoryCode": "Invoice Exchange Voucher", "taxBureauCode": "National Tax", "invoiceIndustryCode": "None", "regionalismCode": "Nanchong City", "batchNumber": "01" }, "invoiceNumber": "0145****", "type": "quota-invoice", "invoiceCode": "15113159****" }, "scene": "ocr" } ], "taskId": "imgzX$vkjvXxi4o74s5NEBba-1s****", "url": "https://aliyundoc.com/test_image_xxxx.png" } ], "requestId": "B5E137FF-668F-48D9-90F7-CE55A9FCC89D" } - Taxi receipt information
{ "msg": "OK", "code": 200, "data": [ { "msg": "OK", "code": 200, "dataId": "test_data_xxxx", "extras": { }, "results": [ { "rate": 99.91, "suggestion": "review", "label": "ocr", "ocrCardInfo": { "carNumber": "A•T****", "date": "September 16, 2008", "totalAmount": "", "getOffTime": "16:58", "amount": "", "invoiceNumber": "5485G0****", "type": "taxi-ticket", "boardingTime": "[K068016:50", "invoiceCode": "25000071****", "actualCollection": "", "mileage": "42.0km" }, "scene": "ocr" } ], "taskId": "img1FrkyyOQXK$7YvhRGMCWb9-1s****", "url": "https://aliyundoc.com/test_image_xxxx.png" } ], "requestId": "D1E56B7A-3876-4284-939A-8004B150D879" }