Image Moderation Pro Asynchronous Detection API-AI Guardrails(AI Guardrails)-阿里云帮助中心

API features

The image moderation Enhanced Edition API identifies content in images that violates regulations, disrupts platform order, or harms the user experience. It supports 60+ content risk labels and 100+ risk control items. Based on the returned risk labels and confidence scores, you can apply moderation rules tailored to your platform policies or industry standards. For more information, see Introduction and billing for image moderation 2.0.

Get started

Register an Alibaba Cloud account: Register Now and follow the on-screen instructions.
Enable pay-as-you-go for Content Moderation: Ensure you have enabled the service. Service activation is free, and you are billed for your API usage. For more information, see Billing details.You can also purchase resource plans. They are more cost-effective than the pay-as-you-go model and ideal for users with high or predictable usage.
Create an AccessKey: Ensure you have created an AccessKey using RAM. If you use a RAM user's AccessKey, you must use the parent Alibaba Cloud account to grant the AliyunYundunGreenWebFullAccess permission to that RAM user. For detailed instructions, see RAM authorization.
Integrate using an SDK: We recommend using an SDK to make API calls. For details, see Image Moderation - Enhanced 2.0 SDK and integration guide.
The Image Moderation - Enhanced asynchronous moderation service includes the following two operations:
- ImageAsyncModeration: Submits an asynchronous image moderation task.
- DescribeImageModerationResult: Queries the result of a moderation task.

Usage

Call this operation to create an asynchronous moderation task. To learn how to construct an HTTP request, see Call API operations by using raw HTTP requests. You can also use a pre-built HTTP request. For more information, see Integration guide.

Operation: ImageAsyncModeration

Supported regions and endpoints:

Region	Public endpoint	Internal endpoint	Supported services
China (Shanghai)	https://green-cip.cn-shanghai.aliyuncs.com	https://green-cip-vpc.cn-shanghai.aliyuncs.com	baselineCheck, baselineCheck_pro, tonalityImprove, aigcCheck, profilePhotoCheck, postImageCheck, advertisingCheck, liveStreamCheck
China (Beijing)	https://green-cip.cn-beijing.aliyuncs.com	https://green-cip-vpc.cn-beijing.aliyuncs.com
China (Hangzhou)	https://green-cip.cn-hangzhou.aliyuncs.com	https://green-cip-vpc.cn-hangzhou.aliyuncs.com
China (Shenzhen)	https://green-cip.cn-shenzhen.aliyuncs.com	https://green-cip-vpc.cn-shenzhen.aliyuncs.com

Billing:

Only requests that return an HTTP status code of 200 are billed. Requests with other status codes are not billed. For more information about billing, see Billing details.
Image requirements:
- Supported formats include PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, and AVIF. For HEIF images, the longest side cannot exceed 8,192 pixels. For GIFs, only the first frame is processed. For ICO files, only the last image is processed.
- The image must not exceed 20 MB. The height or width cannot exceed 30,000 pixels, and the total number of pixels cannot exceed 250 million. For optimal performance, the image resolution should be at least 200 × 200 pixels. Lower resolutions may degrade algorithm performance.
- The image must finish downloading within 3 seconds. Otherwise, the request will time out and return an error.
Results: Asynchronous moderation tasks do not return moderation results in real time. You can obtain the moderation results by using a callback or by polling. The service retains moderation results for up to 3 days.
- Get the moderation result by using a callback: When you submit an asynchronous moderation task, specify the callback request parameter to automatically receive the moderation result.
- Get the moderation result by polling: When you submit an asynchronous moderation task, do not specify the callback request parameter. After the task is submitted, call the result query API to obtain the moderation result. The service queues asynchronous moderation tasks for processing, and the results are typically available within 24 hours.

QPS limit

This API is limited to 100 queries per second (QPS) per user. Exceeding this limit throttles API calls, which can disrupt your service. To request a higher QPS, contact your account manager.

Debug

Use Alibaba Cloud OpenAPI to debug the Image Moderation Pro API online. You can explore sample code, SDK dependencies, and API parameters.

Important

Online debugging uses your logged-in account and counts toward your billable usage.

Request parameters

For the common parameters required in every request, see Common parameters.

The request body is a JSON object that contains the following fields:

Parameter

Type

Required

Example

Description

Service

String

Yes

baselineCheck

The detection service supported by Content Moderation Enhanced. Valid values:

baselineCheck: general baseline detection
baselineCheck_pro: general baseline detection (Professional)
baselineCheck_cb: general baseline detection (International)
tonalityImprove: content governance detection
aigcCheck: AIGC image detection
profilePhotoCheck: profile photo detection
postImageCheck: image detection for posts and comments
advertisingCheck: marketing asset detection
liveStreamCheck: video and live stream screenshot detection

Note

For details on the differences between services, see Service description.

ServiceParameters

JSONString

Yes

Parameters for the content to be moderated, provided as a JSON string. See ServiceParameters for details on each parameter.

Table 1. ServiceParameters

Parameter	Type	Required	Example	Description
imageUrl	String	Required. Content Moderation Enhanced supports three methods for specifying an image. You must choose one of the following: Use an image URL. Specify the `imageUrl` parameter. Use an OSS object. You must specify the `ossBucketName`, `ossObjectName`, and `ossRegionId` parameters. Uploading a local image for moderation does not use your OSS storage, and the file is deleted after 30 minutes. The SDK is integrated with the local image upload feature. For code examples, see Content Moderation Pro 2.0 SDK and integration guide.	https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png	The URL of the image to be moderated. The URL must be publicly accessible. The maximum URL length is 2,048 characters. Note The URL cannot contain Chinese characters. Only one URL is allowed per request.
ossBucketName	String		bucket_01	The name of the authorized OSS bucket. Note To use an internal OSS endpoint, go to the Cloud Resource Access Authorization page with your Alibaba Cloud account (primary account) and grant the `AliyunCIPScanOSSRole` permission.
ossObjectName	String		2022023/04/24/test.jpg	The name of the file in the authorized OSS bucket. Note 1. Specify the original name of the OSS object. Do not include image processing parameters. To use them, specify the image with the `imageUrl` parameter instead. 2. If the filename contains Chinese characters or spaces, use the original filename without URL encoding.
ossRegionId	String		cn-beijing	The region where the OSS bucket is located.
dataId	String	No	img123****	A custom data ID for the object being moderated. Use this ID to map the moderation result to your business data. The ID can be up to 64 characters in length and can contain uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.).
callback	String	No	http://www.aliyundoc.com	The URL to which Content Moderation sends callback notifications about the moderation results. The URL must be an HTTP or HTTPS address. If you omit this parameter, you must poll for the results. Your callback endpoint must support POST requests, UTF-8 encoded payloads, and the form parameters `ReqId`, `Checksum`, and `Content`. Content Moderation calls your callback endpoint with the `ReqId`, `Checksum`, and `Content` parameters to return the result. ReqId: The request ID returned when you submit the asynchronous moderation task. Checksum: A string that is generated by concatenating `User UID + seed + content` and then applying the SHA256 algorithm. The user UID is your Alibaba Cloud account ID, which you can find in the Alibaba Cloud console. To prevent tampering, when you receive a push result, you can generate a string by using the same algorithm and verify it against the provided Checksum. Note The user UID must be the UID of your Alibaba Cloud account, not the UID of a RAM user. Content: A JSON string. Parse it into a JSON object on your side. For an example of the Content result, see the response example in "Query moderation results." Note After your server receives a pushed result from Content Moderation, an HTTP status code of 200 indicates success. If the callback fails (returns a non-200 status code), Content Moderation retries up to three times. After three failed retries, no more attempts are made. We recommend that you check the status of your callback endpoint.
seed	String	No	abc****	A random string used for signing the callback notification request. This value can be up to 64 characters in length and can contain letters, digits, and underscores (_). You can customize this value to verify that the callback notification is initiated by Content Moderation. Note If you specify `callback`, this parameter is required.
cryptType	String	No	SHA256	The encryption algorithm for callback notifications. Content Moderation encrypts the result (a string concatenated from `user UID + seed + content`) with the specified algorithm before sending it to your callback URL. Valid values: SHA256 (default): Uses the SHA-256 algorithm. SM3: Uses the HMAC-SM3 algorithm (a Chinese national cryptographic standard). The service returns a hexadecimal string that consists of lowercase letters and digits. For example, after abc is encrypted by using SM3, a hexadecimal string is returned.
interval	Integer	No	1	The frame extraction interval. This parameter applies only to GIF and long image detection. A GIF image can be considered an array of frames. The `interval` parameter specifies that one frame is extracted every N frames for detection. Long images are classified as long portrait images or long landscape images. For a long portrait image (height > 400 pixels, height-to-width ratio > 2.5), the image is split into floor(height/width) sub-images. For a long landscape image (width > 400 pixels, width-to-height ratio > 2.5), the image is split into floor(width/height) sub-images. If you do not specify this parameter, only the first frame of a GIF image is moderated. For long images, the image is compressed before moderation. Note The `interval` parameter must be used with the `maxFrameNum` parameter. For example, if you set `interval` to 2 and `maxFrameNum` to 10 for GIF or long image detection, one frame is moderated every two frames, up to a maximum of 10 frames. You are billed for the number of frames actually moderated.
maxFrameNum	Integer	No	10	The maximum number of frames to extract. Use this parameter only for GIF and long image detection. The default value is 10. Valid values: 1 to 100. If `interval * maxFrameNum` is less than the total number of frames in the GIF or long image, the frame extraction interval is automatically adjusted to `(Total frames / maxFrameNum)` to improve overall detection accuracy.
referer	String	No	www.aliyun.com	The Referer request header, used for features like hotlink protection. The maximum length is 256 characters.
infoType	String	Yes	customImage,textInImage	The auxiliary information to return in the response. Valid values: `customImage`: information about hits in a custom image library `textInImage`: text detected in the image `publicFigure`: information about public figures `logoData`: logo information You can specify multiple values separated by commas (,). For example, "customImage,textInImage" indicates that both custom image library hits and text in the image are returned. Note Public figure and logo information are returned only when you use a `Service` that supports advanced image moderation. For more information, see Service description.

Response data

Parameter		Type	Example value	Description
Code		Integer	200	The status code. For details, see Code Description.
Msg		String	OK	The response message.
RequestId		String	ABCD1234-1234-1234-1234-123****	The request ID.
Data		Object		The detection result.
	ReqId	String	ABCD1234-1234-1234-1234-123****	The request ID used to query the moderation task result.
	DataId	String	img123******	The ID of the data being detected.

Examples

Sample request:

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

Sample response:

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

Request parameters

Parameter	Type	Required	Example	Description
ReqId	String	Yes	ABCD1234-1234-1234-1234-123****	The RequestId returned by the Image Moderation Pro 2.0 Synchronous Detection API.

Response parameters

Parameter	Type	Example value	Description
RequestId	String	ABCD1234-1234-1234-1234-123****	The unique ID for the request. Alibaba Cloud generates this ID to help you troubleshoot issues.
Data	Object		The image content moderation results. For more information, see Data.
Code	Integer	200	The status code. For more information, see Code description.
Msg	String	OK	The response message.

Table 2. Data

Parameter	Type	Example value	Description
Result	Array		An array of objects that contain the moderation results, such as risk labels and confidence scores. For more information, see Result.
RiskLevel	String	high	The risk level, determined by the configured score thresholds. Valid values: high: high risk medium: medium risk low: low risk none: no risk detected Note We recommend taking immediate action on high-risk content and manually reviewing medium-risk content. Process low-risk content only if high recall is essential. Otherwise, treat low-risk content the same as content with no detected risk. You can configure risk score thresholds in the Content Moderation Console.
DataId	String	img123******	The data ID of the moderated content. Note If a data ID was provided in the request, the same data ID is returned.
FrameNum	Integer	10	The total number of frames extracted from the image.
Frame	String	[{\"Result\":[{\"Confidence\":98.88,\"Label\":\"contraband_gamble\"}],\"tempUrl\":\"http://www.aliyundoc.com/test1.jpg\"}]	A JSON string that contains information about the image frames. It includes the following fields: tempUrl: The temporary URL of the image frame. This URL is valid for 5 minutes. Save the frame image promptly. Result: The moderation results for the frame, including risk labels and confidence scores. For more information, see Result. CustomImage: This field is returned if a match is found in a custom image library. TextInImage: This field is returned if text is detected in the image. PublicFigure: This field is returned if a public figure is detected in the image. LogoData: This field is returned if a logo is detected in the image. Note If the image is not split into frames, this parameter returns information for the original image. If frames are extracted from a GIF or a large image, this parameter returns information for each frame.

Table 3. Result

Parameter	Type	Example value	Description
Label	String	violent_explosion	The risk label assigned to the content. An image can have multiple labels and corresponding scores. For a list of supported labels, see: Supported labels for baselineCheck Supported labels for baselineCheck_pro Supported labels for baselineCheck_cb Supported labels for tonalityImprove Supported labels for aigcCheck Supported labels for profilePhotoCheck Supported labels for postImageCheck Supported labels for advertisingCheck Supported labels for liveStreamCheck
Confidence	Float	81.22	The confidence score, ranging from 0 to 100 and rounded to two decimal places. Some labels do not have a confidence score. For more information, see Risk Label Glossary.
Description	String	Fireworks-related content	A human-readable description of the Label value. Important This description is for reference only and is subject to change. For reliable processing, base your logic on the Label value, not this description.

Examples

Request example

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

Response examples

Response example when risk content is detected:

{
    "Msg": "success",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "pornographic_adultContent",
                "Confidence": 81,
                "Description": "Adult pornography"
            },
            {
                "Label": "sexual_partialNudity",
                "Confidence": 98,
                "Description": "Partial nudity or sexually suggestive"
            },
            {
                "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 example when no risk content is detected:

{
    "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 example for a match in your exemption library:

{
    "Msg": "success",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "nonLabel_lib",
                "Confidence": 99.66,
                "Description": "Hit in exemption 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****"
}

Note

The example requests and responses are formatted for readability. The actual response is a single line of text without line breaks or indentation.

Risk label table

See the Risk Label Description Table for risk label details. You can enable or disable labels and configure detection scopes in the console. For details, see the Console User Guide.

Note

We recommend storing risk labels and confidence scores for future content governance, such as prioritizing manual review and implementing tiered content labeling.

Code

The following table lists the status codes returned by the API. Only requests that return a code of 200 are billed.

Code	Description
200	The request was successful.
280	The task is being processed.
400	A required request parameter is missing.
401	A request parameter is invalid.
402	The length of a request parameter is invalid.
403	The number of requests exceeds the QPS limit.
404	An error occurred while downloading the image.
405	The image download timed out, possibly because the image is inaccessible.
406	The image size exceeds the limit.
407	The image format is not supported.
408	The account does not have permission to call this API. This can occur if the service is not enabled, the account has an overdue payment, or the account lacks authorization.
500	An internal system error occurred.

Image Moderation Enhanced Asynchronous Detection API

API features

Get started

Submit an asynchronous detection task

Usage

QPS limit

Debug

Request parameters

Response data

Examples

Audit task results

API

Rate limit

Debugging

Request parameters

Response parameters

Examples

Risk label table

Code