Submits asynchronous image OCR tasks
Submits asynchronous optical character recognition (OCR) tasks to detect and extract text from images, and queries the results of submitted tasks.
General OCR is available in two versions: standard and advanced.
The standard version is suitable for scenarios that involve a small amount of text, such as movie scenes and Internet images.
The advanced version is suitable for complex document image recognition and scenarios with high text density. It can return information about individual characters.
By default, general OCR detects Chinese and English. To detect content in other languages, you can contact your account manager. The supported languages include Mongolian, Uyghur, Tibetan, Arabic, Russian, French, Spanish, Portuguese, Japanese, Korean, Thai, Vietnamese, Persian, Bengali, German, Dutch, Malay, Italian, Hindi, and Indonesian.
Submit OCR tasks
Operation: POST /green/image/asyncscan
Use this operation to submit images for asynchronous OCR moderation. To construct requests, see Request structure. For SDK-based integration, see SDK overview.
Billing
Calling this operation incurs charges. For billing details, see the Content Moderation pricing page.
Response timeout
The maximum response time for a synchronous moderation request is 6 seconds. If moderation is not completed within 6 seconds, a timeout error is returned. Use asynchronous requests when real-time results are not required.
Returned results
Asynchronous moderation results are not returned in real time. To get results, either poll periodically or configure a callback URL:
-
Callback notification: Set the
callbackparameter when submitting the task. Content Moderation sends results to the specified URL. -
Polling: Omit the
callbackparameter and call/green/image/resultsafter submission to query results. Results are retained for up to 1 hour.
Image requirements
|
Requirement |
Details |
|
URL protocol |
HTTP or HTTPS |
|
Supported formats |
PNG, JPG, JPEG, BMP, GIF, WEBP |
|
Maximum file size |
20 MB |
|
Download timeout |
3 seconds |
|
Recommended resolution |
At least 256 × 256 pixels |
For reliable download performance, store images in Object Storage Service (OSS) or Content Delivery Network (CDN).
QPS limit
10 calls per second per account. Exceeding this limit triggers throttling.
Request parameters
|
Parameter |
Type |
Required |
Example |
Description |
|
bizType |
String |
No |
default |
The business scenario. Create and manage scenarios in the Content Moderation console. For details, see Customize policies for machine-assisted moderation. |
|
scenes |
StringArray |
Yes |
|
The moderation scenario. Set to |
|
callback |
String |
No |
|
The callback URL for receiving asynchronous moderation results. Supports HTTP and HTTPS. If omitted, poll results using |
|
seed |
String |
No |
|
A random string used to generate the callback notification signature. Up to 64 characters: letters, digits, and underscores. Required when |
|
cryptType |
String |
No |
|
The encryption algorithm for the callback notification. Valid values: |
|
tasks |
JSONArray |
Yes |
— |
The list of images to moderate. Up to 100 elements per request. Each element follows the task structure described below. |
|
extras |
JSONObject |
No |
xxx |
If you do not pass the extras parameter, the standard OCR version is used. To use the advanced OCR version, you must pass this parameter in the |
Thechecksumfield in callback notifications uses the UID of your Alibaba Cloud account, not a RAM user ID. To verify a callback, generate a SHA-256 hash ofUID + Seed + Contenton your server and compare it against the receivedchecksum.
Table 1. task
|
Parameter |
Type |
Required |
Example |
Description |
|
dataId |
String |
No |
|
A custom identifier for the image. Must be unique within a request. |
|
url |
String |
Yes |
|
The HTTP or HTTPS URL of the image. Maximum length: 2,048 characters. |
|
interval |
Integer |
No |
|
The frame capture interval for GIF or long images. Specifies that one frame is captured for every |
|
maxFrames |
Integer |
No |
|
The maximum number of frames to capture. Default: 1. Must be used with |
Response parameters
|
Parameter |
Type |
Example |
Description |
|
code |
Integer |
|
The HTTP status code. For a list of status codes, see Common error codes. |
|
msg |
String |
|
The status message. |
|
dataId |
String |
|
The custom identifier from the request. |
|
taskId |
String |
|
The task ID. Use this ID to query results with |
|
url |
String |
|
The URL of the submitted image. |
|
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. |
|
extras |
JSONObject |
— |
The extras value from the request, if provided. This field may change. Always use the latest value. |
Examples
Request
http(s)://[Endpoint]/green/image/asyncscan
&<Common request parameters>
{
"scenes": [
"ocr"
],
"tasks": [
{
"dataId": "test_data_xxxx",
"url": "https://www.aliyundoc.com/test_image_xxxx.png"
}
]
}
Response
{
"code": 200,
"msg": "OK",
"requestId": "92AD868A-F5D2-4AEA-96D4-E1273B8E074C",
"data": [
{
"code": 200,
"msg": "OK",
"dataId": "test_data_xxxx",
"taskId": "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****",
"url": "https://www.aliyundoc.com/test_image_xxxx.png"
}
]
}
Query OCR results
Operation: POST /green/image/results
Queries the results of asynchronous OCR moderation tasks submitted with /green/image/asyncscan. To construct requests, see Request structure. For SDK-based integration, see SDK overview.
Billing
This operation is free of charge.
Polling interval
Query results at least 30 seconds after submitting a task. Results are retained for up to 4 hours.
QPS limit
10 calls per second per account. Exceeding this limit triggers throttling.
Request parameters
|
Parameter |
Type |
Required |
Example |
Description |
|
body |
JSONArray |
Yes |
|
The list of task IDs to query. Up to 100 IDs per request. Obtain task IDs from the response of |
Response parameters
|
Parameter |
Type |
Example |
Description |
|
code |
Integer |
|
The HTTP status code. For a list of status codes, see Common error codes. |
|
msg |
String |
|
The status message. |
|
dataId |
String |
|
The custom identifier from the original request. |
|
taskId |
String |
|
The task ID. |
|
url |
String |
|
The URL of the moderated image. |
|
results |
Array |
— |
The moderation results. When the HTTP status code is 200, this array contains one or more elements, each following the result structure below. |
Table 2. result
|
Parameter |
Type |
Example |
Description |
|
scene |
String |
|
The moderation scenario. Value: |
|
label |
String |
|
The detected content category. Valid values: |
|
suggestion |
String |
|
The recommended action. Valid values: |
|
rate |
Float |
|
The confidence score for the detected category. This field is not meaningful in the OCR scenario. |
|
ocrData |
Array |
— |
All text detected in the image, concatenated. The combined text is typically the first element of the array. |
|
ocrLocations |
Array |
— |
The location and content of each detected text region. Each element follows the ocrLocation structure below. |
|
frames |
Array |
— |
The frames captured from animated images, along with the text detected in each frame. |
|
ocrDetailInfo |
Object |
Detailed text information from the high-precision full-text recognition result. For more information about the structure, see ocrDetailInfo. Note
This result is returned only if you pass |
|
Parameter |
Type |
Example |
Description |
|
text |
String |
|
The text detected in the region. |
|
x |
Float |
|
The horizontal distance from the left edge of the text region to the y-axis. The origin is the upper-left corner of the image. Unit: pixels. |
|
y |
Float |
|
The vertical distance from the top edge of the text region to the x-axis. The origin is the upper-left corner of the image. Unit: pixels. |
|
w |
Float |
|
The width of the text region. Unit: pixels. |
|
h |
Float |
|
The height of the text region. Unit: pixels. |
Table 3. ocrDetailInfo
|
Name |
Type |
Example |
Description |
|
wordNum |
Integer |
2 |
The number of word blocks. |
|
wordsInfo |
Object |
The word block information. For more information about the structure, see wordsInfo. |
Table 4. wordsInfo
|
Name |
Type |
Sample value |
Description |
|
charInfo |
Array |
The single character information. For more information about the structure, see charInfo. |
|
|
direction |
Integer |
0 |
The text direction. Valid values:
|
|
pos |
Array |
The coordinate information. For more information about the structure, see pos. |
|
|
prob |
Integer |
99 |
The confidence level. |
|
word |
String |
Light filters through the forest |
The text content of the word block. |
| Parameter | Type | Example | Description |
| h | Integer | 20 | The height of the word. Unit: pixels. |
| prob | Integer | 99 | The confidence level. |
| w | Integer | 20 | The width of the word. Unit: pixels. |
| word | String | Forest | The content of the word. |
| x | Integer | 39 | The x-coordinate of the word. Unit: pixels. |
| y | Integer | 86 | The y-coordinate of the word. Unit: pixels. |
| Parameter | Type | Example | Description |
| x | Integer | 73 | The x-coordinate of the phrase. Unit: pixels. |
| y | Integer | 113 | The y-coordinate of the phrase. Unit: pixels. |
Examples
Request
http(s)://[Endpoint]/green/image/results
&<Common request parameters>
[
"aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****"
]
Response
{
"code": 200,
"msg": "OK",
"requestId": "992C7849-AA45-4055-8F82-8D44D64C15E3",
"data": [
{
"code": 200,
"msg": "OK",
"dataId": "test_data_xxxx",
"taskId": "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****",
"url": "https://www.aliyundoc.com/test_image_xxxx.png",
"extras": {},
"results": [
{
"scene": "ocr",
"label": "ocr",
"suggestion": "review",
"rate": 99.91,
"ocrData": [
"This topic describes how to call an operation to submit asynchronous image moderation tasks."
],
"ocrLocations": [
{
"text": "This topic describes how to call an operation to submit asynchronous image moderation tasks.",
"x": 31,
"y": 11,
"w": 362,
"h": 19
}
]
}
]
}
]
}
Sample success responses
-
Standard OCR
{ "code": 200, "data": [ { "code": 200, "dataId": "test_data_xxxx", "extras": { }, "msg": "OK", "results": [ { "label": "ocr", "ocrData": [ "This topic describes the details of calling an asynchronous image detection task," ], "ocrLocations": [ { "h": 19, "text": "This topic describes the details of calling an asynchronous image detection task,", "w": 362, "x": 31, "y": 11 } ], "rate": 99.91, "scene": "ocr", "suggestion": "review" } ], "taskId": "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****", "url": "https://www.aliyundoc.com/test_image_xxxx.png" } ], "msg": "OK", "requestId": "992C7849-AA45-4055-8F82-8D44D64C15E3" } -
High-precision Image and Text OCR
{ "msg": "OK", "code": 200, "data": [ { "msg": "OK", "code": 200, "dataId": "test_data_xxxx", "extras": { }, "results": [ { "ocrData": [ "Light filters through the forest, scattered like remaining snow " ], "ocrDetailInfo": { "wordsInfo": [ { "prob": 99, "pos": [ { "x": 37, "y": 86 }, { "x": 123, "y": 86 }, { "x": 123, "y": 109 }, { "x": 37, "y": 109 } ], "word": "Light filters through the forest", "charInfo": [ { "prob": 99, "w": 20, "h": 20, "x": 39, "y": 86, "word": "For" }, { "prob": 99, "w": 5, "h": 20, "x": 63, "y": 86, "word": "est" }, { "prob": 99, "w": 17, "h": 20, "x": 72, "y": 86, "word": "leak" }, { "prob": 99, "w": 17, "h": 20, "x": 103, "y": 86, "word": "ing" } ], "direction": 0 }, { "prob": 99, "pos": [ { "x": 73, "y": 113 }, { "x": 174, "y": 113 }, { "x": 174, "y": 136 }, { "x": 73, "y": 136 } ], "word": "Scattered like remaining snow", "charInfo": [ { "prob": 99, "w": 19, "h": 20, "x": 74, "y": 113, "word": "Scat" }, { "prob": 99, "w": 16, "h": 20, "x": 97, "y": 113, "word": "ter" }, { "prob": 99, "w": 13, "h": 20, "x": 117, "y": 113, "word": "ed" }, { "prob": 99, "w": 16, "h": 20, "x": 134, "y": 113, "word": "like" }, { "prob": 99, "w": 16, "h": 20, "x": 154, "y": 113, "word": "snow" } ], "direction": 0 } ], "wordNum": 2 }, "scene": "ocr", "label": "ocr", "suggestion": "review" } ], "taskId": "aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****", "url": "https://www.aliyundoc.com/test_image_xxxx.png" } ], "requestId": "03E6B458-8DDD-4D44-8856-3216E660201E" }