Synchronous detection-阿里云帮助中心

This topic describes how to call the synchronous image detection API to recognize text using a custom Optical Character Recognition (OCR) template. Custom OCR templates allow you to identify specific text fields in images. When you create an OCR template, you can specify the text to recognize and retrieve the results in a key-value format.

Usage notes

The /green/image/scan 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 an SDK to make API calls. For more information, see SDK overview.

You have created a custom template in the Content Moderation console. For more information, see Custom OCR templates.

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 result:
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. The only valid value is ocr.
tasks	JSONArray	Yes		The detection objects. Each element in the JSON array is a detection task struct. You can submit up to 100 elements to detect 100 pieces of content at a time. To submit 100 elements, you must increase the number of concurrent tasks to 100 or more. For a description of the struct for each element, see task.
extras	JSONObject	Yes	{"card":"template","templateId":"xxx"}	Specifies the OCR template to apply. The format is `{"card":"template","templateId":"xxx"}`. For templateId, enter the ID of the template that you created in the Content Moderation console. For more information about custom OCR templates, see Custom OCR templates.

Table 1. task
Name	Type	Required	Example	Description
dataId	String	No	est_data_xxxx	The data ID of the detection object. This ID can contain uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.), and must be 128 characters or less. Use it to uniquely identify your business data.
url	String	Yes	https://aliyundoc.com/test_image_xxxx.png	The URL of the image to be detected.

Returned 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	imgCjxO0DeXTC7phcds6yrEm-1q****	The ID of the detection task.
url	String	http://aliyundoc.com/test_image_xxxx.png	The URL of the detection object.
extras	JSONObject	XXX	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	JSONArray		The results. If the call is successful (code=200), the response contains one or more elements. Each element is a struct. For a description of the struct, see result.

Table 2. result
Name	Type	Example	Description
scene	String	ocr	The detection scenario. The only valid value is ocr.
label	String	ocr	The classification of the detection result. Valid values: normal: No text is detected in the image. ocr: Text is detected in the image.
suggestion	String	review	The recommended action for the user. Valid values: pass: No action is required. review: Review the detected text.
rate	Float	99.91	In the OCR text and image recognition scenario, you can ignore this return value.
customizeOcrInfo	JSONArray		The information recognized from the custom OCR template. For more information, see customizeOcrInfo. Note This field is present only if the extras request parameter is set to `{"card":"template"}`.

Table 3. customizeOcrInfo
Name	Type	Example	Description
ocrInfo	Array	[{"Date of Birth":"1981.08.03"},{"Validity Period":"2012.12.12-2022.12.11"}]	Each struct in the array is a recognized `key:value` field.

Examples

Sample request

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

Sample success response

{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "msg": "OK",
            "code": 200,
            "dataId": "test_data_xxxx",
            "extras": {

            },
            "results": [
                {
                    "rate": 99.91,
                    "suggestion": "review",
                    "customizeOcrInfo": {
                        "ocrInfo": [
                            {
                                "Date of Birth": "1981.08.03"
                            },
                            {
                                "Validity Period": "2012.12.12-2022.12.11"
                            }
                        ]
                    },
                    "label": "ocr",
                    "scene": "ocr"
                }
            ],
            "taskId": "imgCjxO0DeXTC7phcds6yrEm-1q****",
            "url": "http://aliyundoc.com/test_image_xxxx.png"
        }
    ],
    "requestId": "8ADA8439-4AD7-49BE-8496-2D57F7FB0387"
}