Image Moderation 2.0: Synchronous multi-service detection API
This topic describes how to perform multi-service detection using the Image Moderation 2.0 API. You can pass multiple service parameters in a single API call to invoke multiple detection services at once.
API features
The Image Moderation Pro API identifies content in images that may violate content policies, disrupt community order, or degrade the user experience. It supports 60+ risk labels and 100+ risk control items. Use the rich risk labels and confidence scores from Content Moderation's Image Moderation Pro to further moderate images based on your platform's content policies or industry-specific requirements. For more information, see Introduction to Image Moderation Pro 2.0 and Billing.
The ImageBatchModeration API supports passing multiple Service parameters for a single image to invoke multiple detection services in one request. It does not support submitting multiple image URLs in a single request. To process multiple images, send a separate request for each image.
Getting started
-
Sign up for an Alibaba Cloud account: Sign up now and complete the registration.
-
Activate Content Moderation on a pay-as-you-go basis: Ensure you have activated the service. Activation is free of charge. Once you make API calls, you are automatically billed for your usage. For more information, see Billing.You can also purchase a resource plan to cover your usage. Compared with the post-paid model, resource plans offer tiered discounts and are ideal for users with predictable or high usage.
-
Create an AccessKey pair: Ensure you have created an AccessKey pair in RAM. If you use a RAM user's AccessKey, use your main account to grant the AliyunYundunGreenWebFullAccess permission to that RAM user. For more information, see RAM authorization.
-
Integrate with your app: We recommend using an SDK to call the API. For detailed instructions, see Enhanced Image Moderation 2.0 SDK and Integration Guide.
Usage notes
Call this API to create an image content moderation task. To learn how to construct HTTP requests, see Make HTTP requests. For pre-configured requests, see Getting Started.
-
API operation: ImageBatchModeration
-
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
-
aigcViolationDetection
-
baselineCheckByVL
-
postImageCheckByVL
-
adCheckByVL
China (Hangzhou)
https://green-cip.cn-hangzhou.aliyuncs.com
https://green-cip-vpc.cn-hangzhou.aliyuncs.com
-
baselineCheck
-
baselineCheck_pro
-
tonalityImprove
-
aigcCheck
-
profilePhotoCheck
-
postImageCheck
-
advertisingCheck
-
liveStreamCheck
-
aigcViolationDetection
-
baselineCheckByVL
-
postImageCheckByVL
China (Beijing)
https://green-cip.cn-beijing.aliyuncs.com
https://green-cip-vpc.cn-beijing.aliyuncs.com
-
baselineCheck
-
baselineCheck_pro
-
tonalityImprove
-
aigcCheck
-
profilePhotoCheck
-
postImageCheck
-
advertisingCheck
-
liveStreamCheck
-
aigcViolationDetection
-
baselineCheckByVL
-
postImageCheckByVL
-
adCheckByVL
China (Shenzhen)
https://green-cip.cn-shenzhen.aliyuncs.com
https://green-cip-vpc.cn-shenzhen.aliyuncs.com
-
baselineCheck
-
baselineCheck_pro
-
tonalityImprove
-
aigcCheck
-
profilePhotoCheck
-
postImageCheck
-
advertisingCheck
-
liveStreamCheck
-
aigcViolationDetection
-
baselineCheckByVL
-
postImageCheckByVL
China (Chengdu)
https://green-cip.cn-chengdu.aliyuncs.com
Not available
-
baselineCheck
-
baselineCheck_pro
-
tonalityImprove
-
aigcCheck
-
profilePhotoCheck
-
postImageCheck
-
advertisingCheck
-
liveStreamCheck
-
aigcViolationDetection
-
baselineCheckByVL
-
postImageCheckByVL
-
-
Billing:
This is a billable operation. Billing applies only to successful requests that return an HTTP status code of 200. For billing details, see Billing.
-
Image requirements:
-
Supported image formats: PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, HEIC, GIF, and ICO. For HEIC images, the longest side must be less than 8,192 px. For GIF images, the system processes only the first frame. For ICO files, the system processes only the last image.
-
The image size cannot exceed 20 MB. The height or width cannot exceed 16,384 px, and the total number of pixels cannot exceed 167 million px. For best results, the image resolution should be at least 200 × 200 pixels. A lower resolution may affect the accuracy of the content moderation algorithm.
-
The image must download within 3 seconds. If the download takes longer than 3 seconds, the API returns a download timeout error.
-
QPS limits
The QPS limit for this API is 100 for a single user. API calls exceeding this limit will be rate-limited, which may impact your business. If you require a higher QPS for high-volume use cases or urgent scaling, contact your account manager.
Debug
Before integration, use Alibaba Cloud OpenAPI to debug the ImageBatchModeration API. You can find sample code and SDK dependencies to help you quickly understand the API's usage and parameters.
The online debugging feature uses your logged-in account to call the content moderation API. API calls during debugging are counted toward your billable usage.
Request parameters
For information about the required common request parameters, see Common parameters.
The request body is a JSON object that contains the following fields:
|
Parameter |
Type |
Required |
Example |
Description |
|
Service |
String |
Yes |
baselineCheck,tonalityImprove |
The detection services available for Image Moderation Enhancement. Valid values:
Note
For the differences between services, see Service description. For AIGC-specific services, see AIGC-specific detection service. You can specify multiple services. Separate them with commas (,). For example, |
|
ServiceParameters |
JSONString |
Yes |
A collection of parameters for the content to be moderated. This parameter must be a JSON string. For more information about the fields in the string, see ServiceParameters. |
Table 1. ServiceParameters
|
Parameter |
Type |
Required |
Example |
Description |
|
imageUrl |
String |
Yes. Image Moderation Enhancement supports three methods for specifying an image. You must use one of the following methods:
|
https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png |
The URL of the image to be moderated. The URL must be publicly accessible. The URL cannot exceed 2,048 characters in length. Note
The URL cannot contain Chinese characters. You can specify only one URL per request. |
|
ossBucketName |
String |
bucket_01 |
The name of the authorized OSS bucket. Note
To use an internal OSS endpoint for an image, you must first use your Alibaba Cloud account to grant access on the cloud resource access authorization page. |
|
|
ossObjectName |
String |
2022023/04/24/test.jpg |
The name of the file in the authorized OSS bucket. |
|
|
ossRegionId |
String |
cn-beijing |
The region where the OSS bucket is located. |
|
|
dataId |
String |
No |
img123**** |
The unique identifier for the object to be moderated. The data ID can contain letters, digits, underscores (_), hyphens (-), and periods (.), and cannot exceed 64 characters in length. This ID can be used to uniquely identify your business data. |
|
accountId |
String |
No |
13**** |
The account ID of an end user on the platform. The ID cannot exceed 64 characters in length. |
|
referer |
String |
No |
www.aliyun.com |
The Referer request header. This is used for scenarios such as anti-hotlinking. The header cannot exceed 256 characters in length. |
|
infoType |
String |
Yes |
customImage,textInImage |
The type of supplementary information to retrieve. Valid values:
You can specify multiple values. Separate them with commas (,), for example, Note
Public figure and logo information is returned only when using an advanced image moderation service. For more information, see Service description. |
Response data
|
Parameter |
Type |
Example value |
Description |
|
RequestId |
String |
70ED13B0-BC22-576D-9CCF-1CC12FEAC477 |
The unique request ID generated by Alibaba Cloud. Use this ID to troubleshoot issues. |
|
Data |
Object |
The image moderation results. For more information, see Data. |
|
|
Code |
Integer |
200 |
The status code. For more information, see Status codes. |
|
Msg |
String |
OK |
The response message. |
Table 2. Data
|
Parameter |
Type |
Example value |
Description |
|
Result |
Array |
The moderation results, such as the overall risk label and confidence score. For more information, see Result. |
|
|
RiskLevel |
String |
high |
The risk level, determined by the configured score thresholds. Valid values:
Note
We recommend taking immediate action on |
|
DataId |
String |
img123****** |
The data ID of the moderated object. Note
Returns the value of the |
|
Results |
Array |
The detailed moderation results for each service. For more information, see Results. |
Table 3. Result
|
Parameter |
Type |
Example value |
Description |
|
Label |
String |
violent_explosion |
The moderation label. An image can have multiple labels and scores. For a list of supported labels, see: Note
For labels related to the Content Moderation LLM service, see the Risk Label Glossary for Content Moderation LLM Service. |
|
Confidence |
Float |
81.22 |
The confidence score. A value from 0 to 100, accurate to two decimal places. Some labels do not have a confidence score. For more information, see Risk label definitions. |
|
Description |
String |
Fireworks-related content |
A description of the Important
This parameter provides a human-readable description of the |
Table 4. Results
|
Parameter |
Type |
Example value |
Description |
|
Service |
String |
baselineCheck |
The name of the moderation service used. |
|
RiskLevel |
String |
high |
The risk level, which is determined based on the configured score thresholds. Valid values:
|
|
Result |
Array |
The moderation results, including the risk labels and confidence scores. For more information, see Result. |
|
|
Ext |
Object |
The extended information about the image. For more information, see Extended information. |
Examples
Sample request
{
"Service": "baselineCheck,tonalityImprove",
"ServiceParameters": {
"imageUrl": "https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png",
"dataId": "img123****"
}
}
Sample response
-
If the system detects risk content:
{ "Msg": "OK", "Code": 200, "Data": { "DataId": "img123****", "RiskLevel": "high", "Result": [ { "Label": "violent_explosion", "Confidence": 81.88, "Description": "Fireworks-related content" }, { "Label": "sexual_partialNudity", "Confidence": 98.18, "Description": "Partial nudity or sexually suggestive content" }, { "Label": "pt_programCode", "Confidence": 70.11, "Description": "mini program code" } ], "Results": [ { "Result": [ { "Label": "violent_explosion", "Confidence": 81.88, "Description": "Fireworks-related content" }, { "Label": "sexual_partialNudity", "Confidence": 98.18, "Description": "Partial nudity or sexually suggestive content" } ], "RiskLevel": "high", "Service": "baselineCheck" }, { "Result": [ { "Label": "pt_programCode", "Confidence": 70.11, "Description": "mini program code" } ], "RiskLevel": "high", "Service": "tonalityImprove" } ] }, "RequestId": "ABCD1234-2024-0307-8888-666ZHY" } -
If the system detects no risk content:
{ "Msg": "OK", "Code": 200, "Data": { "DataId": "img123****", "RiskLevel": "none", "Result": [ { "Label": "nonLabel", "Description": "No risks detected" } ], "Results": [ { "Result": [ { "Label": "nonLabel", "Description": "No risks detected" } ], "RiskLevel": "none", "Service": "baselineCheck" }, { "Result": [ { "Label": "nonLabel", "Description": "No risks detected" } ], "RiskLevel": "none", "Service": "tonalityImprove" } ] }, "RequestId": "ABCD1234-2024-0307-8888-666ZHY" }
-
If the image is found in the image exemption library:
{ "Msg": "OK", "Code": 200, "Data": { "DataId": "img123****", "RiskLevel": "none", "Result": [ { "Label": "nonLabel_lib", "Confidence": 83.18, "Description": "Matched an image in the image exemption library" } ], "Results": [ { "Result": [ { "Label": "nonLabel_lib", "Confidence": 83.18, "Description": "Matched an image in the image exemption library" } ], "RiskLevel": "none", "Service": "baselineCheck" }, { "Result": [ { "Label": "nonLabel_lib", "Confidence": 83.18, "Description": "Matched an image in the image exemption library" } ], "RiskLevel": "none", "Service": "tonalityImprove" } ] }, "RequestId": "ABCD1234-1234-1234-1234-1234XYZ" } -
The sample requests and responses are formatted for readability. Actual responses are not indented and do not have line breaks.
Risk tag definitions
See the Risk Tag Definition Table for descriptions of all risk tags. You can enable or disable each risk tag in the console. Some risk tags also let you configure a more granular detection scope. For detailed instructions, see the Console Operation Guide.
We recommend storing the risk tags and confidence scores that the system returns. You can then use this data to prioritize tasks for manual review or labeling and to implement tiered content moderation policies.
Response codes
API response codes. Only requests returning code 200 are billed.
|
Code |
Description |
|
200 |
The request was successful. |
|
400 |
The request parameters are empty. |
|
401 |
The request parameters are invalid. |
|
402 |
A request parameter has an invalid length. Check the parameter and retry the request. |
|
403 |
The request rate exceeds the QPS limit. Check and adjust your concurrency. |
|
404 |
Failed to download the image due to an error or timeout. Verify the image URL and try again. |
|
405 |
The image download timed out, possibly because the image is inaccessible. Check its access settings and try again. |
|
406 |
The input image is too large. Reduce the image size and try again. |
|
407 |
The input image format is not supported. Convert the image and try again. |
|
408 |
Permission to call this API was denied. This can occur if the service is not activated, the account has an overdue payment, or the account lacks authorization. |
|
500 |
A system error occurred. |