Synchronous detection-阿里云帮助中心

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
This is a paid API operation. For more information about billing, see Content Moderation Pricing.
Detection timeout
The maximum detection time for a synchronous detection request is 6 seconds. If the detection is not completed within this time limit, a timeout error is returned. If you do not require real-time results, you can use asynchronous detection. Otherwise, use synchronous detection because its API call is simpler. For these calls, set the timeout period to 6 seconds.
Return results
Synchronous detection requests typically return a result within one second. However, the response time may increase in specific scenarios, such as high system load, large image size, or a large amount of text for optical character recognition (OCR). The processing speed of OCR depends on the number of characters in the image. The more characters, the longer the processing time. If your detection scenario involves images with a large amount of text, we recommend that you use the asynchronous image detection API.
Image requirements
- The image URL must use the HTTP or HTTPS protocol.
- Supported image formats: PNG, JPG, JPEG, BMP, GIF, and WEBP.
- The image size cannot exceed 20 MB for both synchronous and asynchronous calls. The height or width cannot exceed 30,000 pixels (px), and the total number of pixels cannot exceed 250 million (px).
  
  Note
  For GIF images, the total number of pixels cannot exceed 4,194,304 (px), and the height or width cannot exceed 30,000 pixels (px).
- The image must be downloaded within 3 seconds. If the download time exceeds 3 seconds, a download timeout error is returned.
- For optimal performance, we recommend that the image resolution be at least 256x256 pixels. A lower resolution may affect the detection accuracy.
- The response time of the image detection API depends on the image download time. Ensure that the storage service where the image is stored is stable and reliable. For best performance, use Alibaba Cloud Object Storage Service (OSS) or a Content Delivery Network (CDN).

QPS limit

The queries per second (QPS) limit for this API is 10 per user. Exceeding this limit triggers throttling, which can impact your business. Plan your calls accordingly.

Request parameters

Name	Type	Required	Example	Description
bizType	String	No	default	This field identifies your business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize moderation rules.
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: invoice: VAT invoice quota-account-permit: Quota invoice train-ticket: Train ticket taxi-ticket: Taxi receipt

Table 1. task
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 error code. It is the same as the 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 data ID of the detection object. Note If dataId was passed in the detection request, the same dataId 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"}	Additional call parameters, which correspond to the extras parameter in the detection request. Note This parameter may be adjusted. Do not rely on its return value at this time.
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.

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: Text is recognized in the image.
suggestion	String	review	The recommended user action. Valid values: pass: The return value is ignored. review: Review the recognized text.
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: `{"card":"quota-account-permit"}`: Returns quota invoice information. `{"card":"train-ticket"}`: Returns train ticket information. `{"card":"taxi-ticket"}`: Returns taxi receipt information.

Table 3. VAT invoice information (invoiceInfo)
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>7927<>7295<-123020-8>07+63683-80+>314-9+0+/<0-<-/1++359586>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.

Table 4. VAT invoice details (invoice_detail)
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.

ocrCardInfo

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

Request example

Note This example shows how to recognize a VAT invoice (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"
        }
    ]
}

Successful response examples

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"
}