Image Moderation 2.0 Asynchronous Detection API - AI Guardrails

Image Moderation 2.0 detects content in images that violates online regulations, disrupts platform order, or degrades user experience. It supports over 40 risk labels and over 40 risk control items. Use the returned risk labels and confidence scores to build review or governance workflows aligned with your industry standards or platform rules. For billing details, see Image Moderation 2.0 overview and billing.

The asynchronous detection service includes two API operations:

ImageAsyncModeration: Submits an asynchronous image moderation task.
DescribeImageModerationResult: Retrieves the result of a moderation task.

Prerequisites

Before you begin, make sure that you have:

An Alibaba Cloud account. Register now if you don't have one.
Content Moderation activated with pay-as-you-go billing. activated the service if you haven't already. Activation is free; billing starts when you make API calls. For details, see Billing.
An AccessKey created in RAM. If you use a RAM user's AccessKey, grant the RAM user the AliyunYundunGreenWebFullAccess permission using your Alibaba Cloud account. For details, see RAM authorization.
The software development kit (SDK) integrated. See Image Moderation 2.0 SDK and access guide.

ImageAsyncModeration

Submits an asynchronous image moderation task. Results are not returned in real time — retrieve them using a callback or by polling.

Endpoint

Region	Public endpoint	VPC endpoint	Supported services
Singapore	`https://green-cip.ap-southeast-1.aliyuncs.com`	`https://green-cip-vpc.ap-southeast-1.aliyuncs.com`	`baselineCheck_global`

Billing

This is a paid operation. Only requests that return HTTP 200 are billed. For pricing, see Billing.

Rate limit

100 queries per second (QPS) per Alibaba Cloud account. Exceeding this limit throttles your requests. To request a higher QPS limit, contact your account manager.

Debug

Use Alibaba Cloud OpenAPI to debug ImageAsyncModeration online and explore sample code and SDK dependencies.

Important

Online debugging calls the API using your current account and counts toward your billable usage.

Image requirements

Constraint	Limit
Supported formats	PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, HEIF (longest edge < 8,192 px), GIF (first frame only), ICO (last image only)
Max file size	20 MB
Max dimensions	16,384 px per side; 167 million total pixels
Recommended resolution	> 200 × 200 px (low resolution may reduce detection accuracy)
Download timeout	3 seconds (requests that exceed this return a timeout error)

How to pass images

Three methods are supported — choose one per request:

Image URL: Pass imageUrl. The URL must be publicly accessible, up to 2,048 characters, and must not contain Chinese characters.
OSS authorization: Pass ossBucketName, ossObjectName, and ossRegionId. First grant the AliyunCIPScanOSSRole role on the Cloud Resource Access Authorization page.
Local image upload: Handled by the SDK — uploaded files are stored for 30 minutes only. For code examples, see Image Moderation 2.0 SDK and integration guide.

Request parameters

For common request parameters, see Common parameters.

The request body is a JSON object:

Parameter	Type	Required	Example	Description
`Service`	String	Yes	`baselineCheck_global`	The detection service. Valid value: `baselineCheck_global` (general baseline detection). For service differences, see Service description.
`ServiceParameters`	JSONString	Yes		The detection parameters as a JSON string. See the ServiceParameters table below.

ServiceParameters

Parameter	Type	Required	Example	Description
`imageUrl`	String	Conditional	`https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png`	The URL of the image to detect. Required when using the image URL method. The URL must be publicly accessible, up to 2,048 characters, and must not contain Chinese characters. Pass only one URL per request.
`ossBucketName`	String	Conditional	`bucket_01`	The name of the authorized OSS bucket. Required when using the OSS authorization method.
`ossObjectName`	String	Conditional	`2022023/04/24/test.jpg`	The name of the file in the OSS bucket. Pass the original file name as stored in OSS — do not URL-encode it, even if it contains Chinese characters or spaces.
`ossRegionId`	String	Conditional	`cn-beijing`	The region of the OSS bucket. Required when using the OSS authorization method.
`dataId`	String	No	`img123****`	A custom ID to associate with the detected image. Up to 64 characters: letters, digits, underscores (`_`), hyphens (`-`), and periods (`.`).
`callback`	String	No	`http://www.aliyundoc.com`	The callback URL to receive detection results. Supports HTTP and HTTPS. If omitted, poll for results using DescribeImageModerationResult. The callback endpoint must support POST requests with UTF-8 encoding and accept three form parameters: `ReqId`, `Checksum`, and `Content`. Return HTTP 200 to confirm receipt. If your endpoint returns any other status code, Content Moderation retries up to 3 times. If all 3 retries fail, the result is no longer pushed.
`seed`	String	No	`abc****`	A random string used to generate the callback `Checksum`. Required when `callback` is set. Up to 64 characters: letters, digits, and underscores.
`cryptType`	String	No	`SHA256`	The encryption algorithm for callback verification. Content Moderation encrypts `user UID + seed + content` using this algorithm and sends the result as `Checksum`. Valid values: `SHA256` (default), `SM3` (HMAC-SM3, returns lowercase hexadecimal).
`interval`	Integer	No	`1`	The frame capture interval for GIF and long image detection. When set, the system captures one frame for every `interval` frames. If omitted, only the first frame of a GIF is detected, and long images are compressed before detection. Must be used with `maxFrameNum`.
`maxFrameNum`	Integer	No	`10`	The maximum number of frames to capture. Default: `10`. Range: 1–100. If `interval × maxFrameNum` is less than the total number of frames, the interval is automatically adjusted to improve detection coverage. Billing is based on the actual number of frames detected.
`referer`	String	No	`www.aliyun.com`	The `Referer` request header, for scenarios such as hotlink protection. Up to 256 characters.
`infoType`	String	Yes	`customImage,textInImage`	The types of auxiliary information to return. Valid values: `customImage` (custom image library hits), `textInImage` (text in image), `publicFigure` (public figure hits), `logoData` (logo hits). Specify multiple types separated by commas.

Long image detection logic

Long images are detected when interval is set:

Long vertical image (height > 400 px and height-to-width ratio > 2.5): sliced into round(height / width) sections.
Long horizontal image (width > 400 px and width-to-height ratio > 2.5): sliced into round(width / height) sections.

Callback verification

The Checksum is computed as SHA256 (or SM3) of user UID + seed + content, where user UID is your Alibaba Cloud account ID — not a RAM user ID. To verify authenticity, recompute the checksum on your server and compare it against the received Checksum.

Find your Alibaba Cloud account ID in the Alibaba Cloud Management Console.

Response elements

Parameter	Type	Example	Description
`Code`	Integer	`200`	The status code. See Status codes.
`Msg`	String	`OK`	The response message.
`RequestId`	String	`ABCD1234-1234-1234-1234-123****`	The request ID.
`Data`	Object		The detection result.
`Data.ReqId`	String	`ABCD1234-1234-1234-1234-123****`	The request ID for querying the moderation result. Pass this value to DescribeImageModerationResult.
`Data.DataId`	String	`img123******`	The data ID corresponding to the detected image.

Examples

Request

{
    "Service": "baselineCheck",
    "ServiceParameters": {
        "imageUrl": "https://img.alicdn.com/tfs/TB1Mq6ZmCslXu8jSZFuXXXg7FXa-1440-568.jpg",
        "dataId": "img123******",
        "interval": 1,
        "maxFrameNum": 50
    }
}

Response

{
    "Msg": "OK",
    "Code": 200,
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ",
    "Data": {
        "ReqId": "ABCD1234-1234-1234-1234-1234XYZ",
        "DataId": "img123******"
    }
}

DescribeImageModerationResult

Retrieves the result of an Image Moderation 2.0 moderation task. This operation is not billed.

We recommend polling for results at least 30 seconds after submitting the task, using 30 seconds as the query interval. Results are stored for 3 days and automatically deleted afterward. When polling without a callback, results are typically available within 24 hours.

Rate limit

100 QPS per Alibaba Cloud account.

Debug

Use Alibaba Cloud OpenAPI to debug DescribeImageModerationResult online.

Request parameters

Parameter	Type	Required	Example	Description
`ReqId`	String	Yes	`ABCD1234-1234-1234-1234-123****`	The request ID returned by ImageAsyncModeration (`Data.ReqId`).

Response elements

Parameter	Type	Example	Description
`Code`	Integer	`200`	The status code. See Status codes.
`Msg`	String	`OK`	The response message.
`RequestId`	String	`ABCD1234-1234-1234-1234-123****`	The request ID.
`Data`	Object		The image detection result.

Data

Parameter	Type	Example	Description
`DataId`	String	`img123****`	The data ID from the original detection request.
`RiskLevel`	String	`high`	The overall risk level. Valid values: `high`, `medium`, `low`, `none`. See Risk level handling.
`Result`	Array		The detected risk labels and confidence scores. See the Result table below.
`FrameNum`	Integer	`10`	The total number of frames captured from the image.
`Frame`	String		A JSON string containing per-frame detection results. Each frame includes: `tepmUrl` (temporary URL, valid for 5 minutes), `Result`, and optionally `CustomImage`, `TextInImage`, `PublicFigure`, and `LogoData`. When no frames are captured, only the current image result is returned.

Result

Parameter	Type	Example	Description
`Label`	String	`violent_explosion`	The risk label. A single image may return multiple labels. For supported labels, see Labels supported by general baseline detection. 2.0
`Confidence`	Float	`81.22`	The confidence score, from 0 to 100 with two decimal places. Some labels do not return a confidence score.
`Description`	String	`Fireworks content`	A human-readable description of the label. This field is for reference only and may change — base your processing logic on `Label`, not `Description`.

Risk level handling

Risk level	Recommended action
`high`	Handle directly (block or remove content)
`medium`	Route to manual review
`low`	Process only when high recall is required; otherwise treat as `none`
`none`	No risk detected

Configure risk score thresholds in the Content Moderation console.

Examples

Request

{
    "ReqId": "ABCD1234-1234-1234-1234-123****"
}

Response — risky content detected

{
    "Msg": "success",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "pornographic_adultContent",
                "Confidence": 81,
                "Description": "Adult pornography"
            },
            {
                "Label": "sexual_partialNudity",
                "Confidence": 98,
                "Description": "Body nudity or sexual content"
            },
            {
                "Label": "violent_explosion",
                "Confidence": 70,
                "Description": "Fireworks content"
            },
            {
                "Label": "violent_explosion_lib",
                "Confidence": 81,
                "Description": "Fireworks content_hit in custom library"
            }
        ],
        "RiskLevel": "high",
        "Frame": "[{\"Result\":[{\"Confidence\":98.18,\"Label\":\"contraband_gamble\"},{\"Confidence\":96.39,\"Label\":\"pornographic_adultContent\"},{\"Confidence\":95.27,\"Label\":\"violent_explosion\"}],\"TempUrl\":\"http://www.aliyundoc.com/test1.jpg\"},{\"Result\":[{\"Confidence\":91.18,\"Label\":\"violent_explosion_lib\"}],\"TempUrl\":\"http://www.aliyundoc.com/test2.jpg\"}]",
        "FrameNum": 2
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

Response — no risky content

{
    "Msg": "success",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "nonLabel",
                "Confidence": null,
                "Description": "No risk detected"
            }
        ],
        "RiskLevel": "none",
        "Frame": "[{\"Result\":[{\"Label\":\"nonLabel\"}],\"TempUrl\":\"http://www.aliyundoc.com/test1.jpg\"},{\"Result\":[{\"Label\":\"nonLabel\"}],\"TempUrl\":\"http://www.aliyundoc.com/test2.jpg\"}]",
        "FrameNum": 2
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

Response — image matched in review-free library

{
    "Msg": "success",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "nonLabel_lib",
                "Confidence": 99.66,
                "Description": "Hit in review-free library"
            }
        ],
        "RiskLevel": "none",
        "Frame": "[{\"Result\":[{\"Confidence\":99.66,\"Label\":\"nonLabel_lib\"}],\"TempUrl\":\"http://www.aliyundoc.com/test1.jpg\"},{\"Result\":[{\"Confidence\":81.18,\"Label\":\"nonLabel_lib\"}],\"TempUrl\":\"http://www.aliyundoc.com/test2.jpg\"}]",
        "FrameNum": 2
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

The request and response examples use line breaks and indentation for readability. Actual API responses are not formatted.

Risk label description table

For descriptions of all risk labels, see Risk label description table. Labels can be enabled or disabled in the console, and some support more granular detection scopes. For configuration details, see Console user guide.

Store the risk labels and confidence scores returned by the API for a period of time. This allows you to reference them for future content governance, set priorities for manual review, and implement tiered and categorized governance measures.

Status codes

The system bills only requests that return code 200. All other codes are not billed.

Code	Description
`200`	The request succeeded.
`280`	The task is being processed.
`400`	A request parameter is empty.
`401`	A request parameter is incorrect.
`402`	A request parameter exceeds the allowed length. Check and adjust the value.
`403`	The request exceeds the QPS limit. Reduce your request rate.
`404`	Failed to download the image. Check the image URL or retry.
`405`	The image download timed out. The image may be inaccessible. Check and retry.
`406`	The image is too large. Reduce the image size and retry.
`407`	The image format is not supported. Check the format and retry.
`408`	The account does not have permission to call this operation. Make sure the service is activated, the account has no overdue payments, and the calling account is authorized.
`500`	A system error occurred.