Call /green/image/asyncscan to perform general OCR - AI Guardrails

Submits asynchronous optical character recognition (OCR) tasks to detect and extract text from images, and queries the results of submitted tasks.

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 callback parameter when submitting the task. Content Moderation sends results to the specified URL.
Polling: Omit the callback parameter and call /green/image/results after 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	`["ocr"]`	The moderation scenario. Set to `ocr`.
callback	String	No	`http://www.aliyundoc.com/xx.json`	The callback URL for receiving asynchronous moderation results. Supports HTTP and HTTPS. If omitted, poll results using `/green/image/results`. The endpoint must support POST requests, use UTF-8 encoding, and accept the `checksum` and `content` parameters. Content Moderation sends results to the URL with these fields: `checksum` (a SHA-256 hash of `UID + Seed + Content` for tamper verification) and `content` (a JSON-formatted string containing the moderation result). If your server returns HTTP 200, the delivery is considered successful. On failure, Content Moderation retries up to 16 times before stopping.
seed	String	No	`aabbcc123`	A random string used to generate the callback notification signature. Up to 64 characters: letters, digits, and underscores. Required when `callback` is set.
cryptType	String	No	`SHA256`	The encryption algorithm for the callback notification. Valid values: `SHA256` (default, uses HMAC-SHA256) and `SM3` (uses HMAC-SM3, returns a hexadecimal lowercase string).
tasks	JSONArray	Yes	—	The list of images to moderate. Up to 100 elements per request. Each element follows the task structure described below.

The checksum field 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 of UID + Seed + Content on your server and compare it against the received checksum.

Table 1. task

Parameter	Type	Required	Example	Description
dataId	String	No	`test_data_xxxx`	A custom identifier for the image. Must be unique within a request.
url	String	Yes	`https://www.aliyundoc.com/test_image_xxxx.png`	The HTTP or HTTPS URL of the image. Maximum length: 2,048 characters.
interval	Integer	No	`2`	The frame capture interval for GIF or long images. Specifies that one frame is captured for every `n` frames. Must be used with `maxFrames`. By default, only the first frame is moderated. For GIF images, `n` is the total frame count. For long portrait images (height > 400 px, height-to-width ratio > 2.5:1), frame count = height ÷ width (rounded). For long horizontal images (width > 400 px, width-to-height ratio > 2.5:1), frame count = width ÷ height (rounded).
maxFrames	Integer	No	`100`	The maximum number of frames to capture. Default: 1. Must be used with `interval`. If `interval × maxFrames` is less than the total frame count, the capture interval is automatically adjusted to distribute captures evenly across the image. Fees are calculated based on the actual number of frames moderated.

Response parameters

Parameter	Type	Example	Description
code	Integer	`200`	The HTTP status code. For a list of status codes, see Common error codes.
msg	String	`OK`	The status message.
dataId	String	`test_data_xxxx`	The custom identifier from the request.
taskId	String	`aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****`	The task ID. Use this ID to query results with `/green/image/results`.
url	String	`https://www.aliyundoc.com/test_image_xxxx.png`	The URL of the submitted image.
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	`["aaa25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"]`	The list of task IDs to query. Up to 100 IDs per request. Obtain task IDs from the response of `/green/image/asyncscan`.

Response parameters

Parameter	Type	Example	Description
code	Integer	`200`	The HTTP status code. For a list of status codes, see Common error codes.
msg	String	`OK`	The status message.
dataId	String	`test_data_xxxx`	The custom identifier from the original request.
taskId	String	`aaa25f95-4892-4d6b-aca9-7939bc6e9baa-148619876****`	The task ID.
url	String	`https://www.aliyundoc.com/test_image_xxxx.png`	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	`ocr`	The moderation scenario. Value: `ocr`.
label	String	`ocr`	The detected content category. Valid values: `normal` (no text detected) and `ocr` (text detected).
suggestion	String	`review`	The recommended action. Valid values: `pass` (no action required) and `review` (manual review required).
rate	Float	`99.91`	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.

Parameter	Type	Example	Description
text	String	`hello`	The text detected in the region.
x	Float	`41`	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	`84`	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	`83`	The width of the text region. Unit: pixels.
h	Float	`26`	The height of the text region. Unit: pixels.

Table 3. ocrDetailInfo

Table 4. wordsInfo

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

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

            },
            "msg": "OK",
            "results": [
                {
                    "label": "ocr",
                    "ocrData": [
                        "This topic describes how to call an operation to submit asynchronous image moderation tasks."
                    ],
                    "ocrLocations": [
                        {
                            "h": 19,
                            "text": "This topic describes how to call an operation to submit asynchronous image moderation tasks.",
                            "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"
}