AI Guardrails:Synchronous detection

Prerequisites

Before you begin, make sure you have:

• An Alibaba Cloud account with Content Moderation enabled

• An AccessKey ID and AccessKey Secret

• Images accessible via public HTTP or HTTPS URLs

How it works

1. Submit a request to /green/image/scan with scenes set to ["ocr"] and a list of image URLs.

2. Content Moderation downloads each image, runs OCR, and returns the detected text and bounding box coordinates.

3. Check the suggestion field in the response to decide whether the detected text requires manual review.

Results are typically returned within 1 second. The maximum response time is 6 seconds; requests that exceed this limit return a timeout error.

Usage notes

Billing: Calling this operation incurs charges. For pricing details, see the billing documentation.

Image download timeout: If an image cannot be downloaded within 3 seconds, the request returns a timeout error. Store images in a stable, low-latency service such as Object Storage Service (OSS) or Content Delivery Network (CDN) to minimize download failures.

Text-heavy images: OCR processing time increases with the number of words in an image. For images containing large amounts of text — such as scanned documents — use asynchronous moderation instead.

Image requirements:

• Protocol: HTTP or HTTPS URLs only

• Formats: PNG, JPG, JPEG, BMP, GIF, WEBP

• Maximum size: 20 MB (applies to both synchronous and asynchronous moderation)

• Minimum recommended resolution: 256 × 256 pixels

QPS limits

This operation supports up to 10 requests per second (QPS) per account. Exceeding this limit triggers throttling.

Submit a request

Endpoint

POST http(s)://[Endpoint]/green/image/scan

Request parameters

Task parameters

Each element in the tasks array describes one image to scan.

The interval and maxFrames parameters must be used together.

Interpret the response

A successful call (HTTP 200) returns a data array where each element corresponds to one submitted image.

Response fields

Result fields

Each element in results contains the OCR output for the image.

ocrLocation fields

Each entry in ocrLocations describes one detected text region. The coordinate origin is the upper-left corner of the image, with x increasing to the right and y increasing downward.

ocrData contains the combined text from all detected regions as a single string. ocrLocations gives the position of each individual text region. Use ocrLocations when you need to locate or highlight specific text within the image.

GIF and long image moderation

By default, only the first frame of a GIF or long image is scanned. Use interval and maxFrames together to scan multiple frames.

• interval: Scan one frame out of every n frames, where n is the value of interval.

• maxFrames: Cap the total number of frames scanned.

If interval × maxFrames is less than the total number of frames in the image, the system automatically adjusts the interval to ceil(total_frames / maxFrames) to distribute coverage evenly.

What counts as a long image:

Example: With interval: 2 and maxFrames: 100, the system scans one frame out of every two frames, up to a maximum of 100 frames. Charges apply per frame scanned.

Example

Request

POST http(s)://[Endpoint]/green/image/scan
<Common request parameters>

{
    "scenes": ["ocr"],
    "tasks": [
        {
            "dataId": "test_data_xxxx",
            "url": "https://aliyundoc.com/test_image_xxxx.png"
        }
    ]
}

Response

{
    "code": 200,
    "msg": "OK",
    "requestId": "C4AB08A9-AD75-4410-859B-0B9EF6DFC3C4",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "test_data_xxxx",
            "taskId": "img5A@k7a@B4q@6K@d9nfKgOs-1s****",
            "url": "https://aliyundoc.com/test_image_xxxx.png",
            "extras": {},
            "results": [
                {
                    "scene": "ocr",
                    "label": "ocr",
                    "suggestion": "review",
                    "rate": 99.91,
                    "ocrData": [
                        "hello, this is a test text."
                    ],
                    "ocrLocations": [
                        {
                            "text": "hello",
                            "x": 41,
                            "y": 84,
                            "w": 83,
                            "h": 26
                        },
                        {
                            "text": " this is a test text.",
                            "x": 78,
                            "y": 114,
                            "w": 95,
                            "h": 25
                        }
                    ]
                }
            ]
        }
    ]
}

In this example, suggestion: review means the detected text requires human review before taking further action. ocrData contains the full combined string "hello, this is a test text.", while ocrLocations gives the exact pixel position of each text fragment within the image.

What's next

• SDK overview — Use a pre-built client instead of constructing raw HTTP requests.

• Request structure — Learn how to construct and sign requests.

• Customize policies for machine-assisted moderation — Configure custom moderation policies using bizType.