AI Guardrails:Synchronous moderation API for Image Moderation 2.0

API description

The Image Moderation 2.0 API detects images for regulatory violations, platform policy breaches, and harmful content. It supports more than 40 risk labels and more than 40 risk control items. Use the returned risk labels and confidence scores to take moderation or administrative action based on your business requirements. For more information, see Introduction to Image Moderation 2.0 and Billing.

Connection guide

1. Create an Alibaba Cloud account. Register now and follow the on-screen instructions.

2. Activate the pay-as-you-go Content Moderation service. Make sure that you have activated the service. Activation is free. After you start using the service, you are charged based on your usage. For more information, see Billing details.

3. Create an AccessKey. Use Resource Access Management (RAM) to create an AccessKey. If you use a RAM user AccessKey, grant the AliyunYundunGreenWebFullAccess permission to the RAM user. For more information, see RAM authorization.

4. Integrate with SDKs. Use SDKs to call the API. For more information, see Image Moderation 2.0 SDKs and usage guide.

Usage notes

Call the Image Moderation 2.0 API to create a task for image moderation. For more information about constructing an HTTP request, see Make HTTPS calls. You can also use an SDK. For more information, see Image Moderation 2.0 SDKs and usage guide.

• API operation: ImageModeration

• Supported regions and endpoints:

The UK (London) region reuses the console configurations of the Singapore region. The US (Silicon Valley) and Germany (Frankfurt) regions reuse the console configurations of the US (Virginia) region.

• Billing:

This API operation is billable. Only requests that return an HTTP status code of 200 are charged. Requests that return other error codes are not billed. For more information, see Billing details.

• Image requirements:

  • Supported formats: PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, HEIF (the longest edge must be less than 8,192 px), GIF (only the first frame is used), and ICO (only the last image is used).

  • Maximum file size: 20 MB. The height or width cannot exceed 16,384 px, and the total pixel count cannot exceed 167 million. For best results, use images with a resolution greater than 200 x 200 px. Low resolution may reduce moderation accuracy.

  • Image download timeout: 3 seconds. If the download exceeds this limit, a timeout error is returned.

QPS limit

The queries per second (QPS) limit for a single user is 100 calls/second. If you exceed this limit, API calls are throttled, which may affect your business. To request a higher QPS or scale out urgently, contact your business manager.

Debug

Before you connect, use Alibaba Cloud OpenAPI Explorer to debug the Image Moderation 2.0 API online. View sample code and SDK dependency information to understand how to use the API and its parameters.

Request parameters

For more information about the common request parameters that must be included in a request, see Common parameters.

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

Table 1. ServiceParameters

Response data

Table 2. Data

Table 3. result

Auxiliary information returned (click to expand)

Table 4. Ext

Table 5. CustomImage

Table 6. TextInImage

Table 7. OcrResult

Table 8. CustomText

Table 9. PublicFigure

Table 10. LogoData

Table 11. Logo

Table 12. Location

Examples

Request example

{
    "Service": "baselineCheck_global",
    "ServiceParameters": {
        "imageUrl": "https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png",
        "dataId": "img123****"
    }
}

Response example

• If the system detects risky content, the following response is returned:

{
    "Msg": "OK",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "pornographic_adultContent",
                "Confidence": 81,
                "Description": "Adult pornographic content"
            },
            {
                "Label": "sexual_partialNudity",
                "Confidence": 98,
                "Description": "Partial nudity or sexy"
            },
            {
                "Label": "violent_explosion",
                "Confidence": 70,
                "Description": "Fireworks content"
            },
            {
                "Label": "violent_explosion_lib",
                "Confidence": 81,
                "Description": "Fireworks content_Hit custom library"
            }
        ],
        "RiskLevel": "high"
    },
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ"
}

• If the system does not detect any risky content, the following response is returned:

{
    "Msg": "OK",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "nonLabel",
                "Description": "No risk detected"
            }
        ],
        "RiskLevel": "none"
    },
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ"
}

• If the submitted image matches an image in your configured allowlist, the following response is returned:

{
    "Msg": "OK",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "nonLabel_lib",
                "Confidence": 83,
                "Description": "Hit allowlist"
            }
        ],
        "RiskLevel": "none"
    },
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ"
}

• Auxiliary information response example (click to expand)

  • When a custom image library is matched, the following response is returned:

{
    "Code": 200,
    "Data": {
        "DataId": "",
        "Ext": {
            "CustomImage": [
                {
                    "ImageId": "12345",
                    "LibId": "TEST20240307",
                    "LibName": "Risk Image Library A"
                }
            ]
        },
        "Result": [
            {
                "Confidence": 100.0,
                "Label": "pornographic_adultContent_lib",
                "Description": "Adult pornographic content_Hit custom library"
            }
        ],
        "RiskLevel": "high"
    },
    "Msg": "success",
    "RequestId": "5F572704-4C03-51DF-8957-D77BF6E7444E"
}

• When a custom keyword library is matched, the following response is returned:

{
    "Code": 200,
    "Data": {
        "DataId": "",
        "Ext": {
            "TextInImage": {
                "CustomText": [
                    {
                        "KeyWords": "Custom Keyword 1",
                        "LibId": "TEST20240307",
                        "LibName": "Text Blacklist A"
                    }
                ],
                "OcrResult": [
                    {
                        "Text": "Text line 1"
                    },
                    {
                        "Text": "Text line 2"
                    },
                    {
                        "Text": "Text line 3 with custom keyword"
                    }
                ],
                "RiskWord": null
            }
        },
        "Result": [
            {
                "Confidence": 99.0,
                "Label": "pornographic_adultContent_tii_lib",
                "Description": "Text contains pornographic content_Hit custom library"
            }
        ],
        "RiskLevel": "high"
    },
    "Msg": "success",
    "RequestId": "TESTZGL-0307-2024-0728-FOREVER"
}

• When a text violation in an image is detected, the following response is returned:

{
    "Code": 200,
    "Data": {
        "DataId": "",
        "Ext": {
            "TextInImage": {
                "CustomText": null,
                "OcrResult": [
                    {
                        "Text": "Text line 1"
                    },
                    {
                        "Text": "Text line 2"
                    },
                    {
                        "Text": "Text line 3 with risk content"
                    }
                ],
                "RiskWord": [
                    "Risk Word 1"
                ]
            }
        },
        "Result": [
            {
                "Confidence": 89.15,
                "Label": "political_politicalFigure_name_tii",
                "Description": "Text contains leader's name"
            }
        ],
        "RiskLevel": "high"
    },
    "Msg": "success",
    "RequestId": "TESTZGL-0307-2024-0728-FOREVER"
}

• When logo information is detected, the following response is returned:

{
    "Code": 200,
    "Data": {
        "DataId": "",
        "Ext": {
            "LogoData": [
                {
                    "Location": {
                        "H": 44,
                        "W": 100,
                        "X": 45,
                        "Y": 30
                    },
                    "Logo": [
                        {
                            "Confidence": 96.15,
                            "Label": "pt_logotoSocialNetwork",
                            "Name": "CCTV"
                        }
                    ]
                }
            ]
        },
        "Result": [
            {
                "Confidence": 96.15,
                "Label": "pt_logotoSocialNetwork",
                "Description": "Social platform logo"
            }
        ],
        "RiskLevel": "high"
    },
    "Msg": "success",
    "RequestId": "TESTZGL-0307-2024-0728-FOREVER"
}

• When person information is detected, the following response is returned:

{
    "Code": 200,
    "Data": {
        "DataId": "",
        "Ext": {
            "PublicFigure": [
                {
                    "FigureId": null,
                    "FigureName": "Yang San",
                    "Location": [
                        {
                            "H": 520,
                            "W": 13,
                            "X": 14,
                            "Y": 999
                        }
                    ]
                }
            ]
        },
        "Result": [
            {
                "Confidence": 92.05,
                "Label": "political_politicalFigure_3",
                "Description": "Provincial and municipal government personnel"
            }
        ],
        "RiskLevel": "high"
    },
    "Msg": "success",
    "RequestId": "TESTZGL-0307-2024-0728-FOREVER"
}

The request and response examples in this document are formatted for readability. Actual results are not formatted with line breaks or indentation.

Risk label definitions

The following describes the risk label values, their score ranges, and their meanings. Enable or disable each risk label in the console. For some risk labels, you can configure a more granular detection scope. For more information, see the Console User Guide. The labels supported by each image service are listed below.

For labels returned when no risk is detected or the allowlist is matched, see Supported labels when there is no risk or the allowlist is matched.

Store the risk labels and confidence scores returned by the system for a period. This allows you to reference them for subsequent content governance. Set priorities for manual review or annotation, and implement layered and categorized content governance measures based on the risk labels.

Table 4. Labels supported by general baseline check (baselineCheck_global)

tii is an abbreviation for "text in image". A label ending in tii indicates that a text violation was detected in the image. You can also configure custom image libraries for each risk label. If a moderated image closely matches an image in a custom library, the system returns the corresponding risk label with _lib appended. For example, if you configure a custom image library for "violent_explosion" and a moderated image matches an image in that library, the system returns violent_explosion_lib in the label parameter. The confidence parameter represents the similarity score.

If the system detects no anomalies in the submitted image, or if it closely matches an image in your configured allowlist, the returned label and confidence score are as shown in the table below.

Code descriptions

The following table describes the response codes returned by the API. Only requests that return an HTTP status code of 200 are charged. Requests that return other error codes are not billed.