Call /green/image/scan to moderate images in real time - Content Moderation - Alibaba Cloud - AI Guardrails

Submits synchronous image moderation tasks and returns results in real time. Use this operation to detect pornographic content, terrorist content, ad violations, QR codes, undesirable scenes, and logos in images.

Supported scenarios

Scene value	Scenario	Labels returned
`porn`	Pornography detection	`normal`, `porn`, `sexy`
`terrorism`	Terrorist content detection	`normal`, `bloody`, `explosion`, `outfit`, `logo`, `weapon`, `politics`, `violence`, `crowd`, `parade`, `carcrash`, `flag`, `location`, `drug`, `gamble`, `others`
`ad`	Ad violation detection	`normal`, `politics`, `porn`, `abuse`, `terrorism`, `contraband`, `spam`, `npx`, `qrcode`, `programCode`, `ad`
`qrcode`	QR code detection	`normal`, `qrcode`, `programCode`
`live`	Undesirable scene detection	`normal`, `meaningless`, `PIP`, `smoking`, `drivelive`, `drug`, `gamble`
`logo`	Logo detection	`normal`, `TV`, `trademark`

Usage notes

Response time: Results are typically returned within 1 second. The maximum allowed response time is 6 seconds — set your client timeout accordingly. In high-load scenarios or when images are large or text-heavy, response time may increase.

Image requirements:

Supported formats: PNG, JPG, JPEG, BMP, GIF, WEBP
Maximum size: 20 MB
Download timeout: 3 seconds. If the image cannot be downloaded within 3 seconds, a timeout error is returned.
Minimum recommended resolution: 256 × 256 pixels
URLs must be HTTP or HTTPS, up to 2,048 characters

Storage: Moderation response time depends on image download speed. Use a stable storage service such as Object Storage Service (OSS) or Content Delivery Network (CDN) to host images.

Multiple scenarios: Specifying multiple scenes in a single request incurs the cumulative fee of all specified scenarios.

GIF and long images: By default, only the first frame is moderated. Use interval and maxFrames together to moderate additional frames. Billing is based on the actual number of frames moderated.

Asynchronous moderation: This operation returns results synchronously. If you do not need real-time results, use the asynchronous moderation operation instead.

QPS limit

50 calls per second per account. Exceeding this limit triggers throttling.

Request syntax

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

Request parameters

Top-level parameters

Parameter	Type	Required	Example	Description
`bizType`	String	No	`default`	The business scenario. Create business scenarios in the Content Moderation console. For more information, see Customize policies for machine-assisted moderation.
`scenes`	StringArray	Yes	`["porn","terrorism"]`	The moderation scenarios. Valid values: `porn`, `terrorism`, `ad`, `qrcode`, `live`, `logo`. Specify multiple values to run multiple scenarios in a single request.
`tasks`	JSONArray	Yes	—	The moderation tasks to submit. Each element is a `task` object. Maximum: 100 elements per request. To submit 100 tasks at a time, you must raise the relevant concurrency limit to a number greater than 100.

task

Parameter	Type	Required	Example	Description
`clientInfo`	JSONObject	No	`{"userId":"12023****","userNick":"Mike","userType":"others"}`	The client information. For the structure, see the "Common request parameters" section of Common parameters. The task-level `clientInfo` takes priority over the global one.
`dataId`	String	No	`cfd33235-71a4-468b-8137-a5ffe323****`	The ID of the object to moderate. Accepted characters: letters, digits, underscores (`_`), hyphens (`-`), and periods (`.`). Maximum length: 128 characters. This ID is returned in the response for correlation.
`url`	String	Yes	`http://www.aliyundoc.com/xxx.jpg`	The publicly accessible HTTP or HTTPS URL of the image. Maximum length: 2,048 characters.
`extras`	JSONObject	No	—	Additional parameters. Not required for standard image moderation.
`interval`	Integer	No	`2`	The frame sampling interval for GIF or long image moderation. One frame is captured for every `interval` frames. Must be used together with `maxFrames`.
`maxFrames`	Integer	No	`10`	The maximum number of frames to capture from a GIF or long image. Default value: 1. If `interval × maxFrames` is less than the total frame count, the system automatically adjusts the interval to evenly distribute captures across the image.

Long image frame count calculation:

Orientation	Condition	Frame count
Portrait	Height > 400 px, height/width ratio > 2.5	round(height / width)
Horizontal	Width > 400 px, width/height ratio > 2.5	round(width / height)

Response parameters

Top-level fields

Parameter	Type	Example	Description
`code`	Integer	`200`	The HTTP status code. For a list of status codes, see Common error codes.
`msg`	String	`OK`	The response message.
`requestId`	String	`69B41AE8-1234-1234-1234-12D395695D2D`	The request ID.
`data`	JSONArray	—	The moderation results, one element per submitted task. Each element contains the fields described in the following sections.

Per-task fields

Parameter	Type	Example	Description
`code`	Integer	`200`	The HTTP status code for this task.
`msg`	String	`OK`	The response message for this task.
`dataId`	String	`cfd33235-71a4-468b-8137-a5ffe323****`	The ID of the moderated object, echoed from the request.
`taskId`	String	`img4wlJcb7p4wH4lAP3111111-123456`	The moderation task ID.
`url`	String	`http://www.aliyundoc.com/xxx.jpg`	The URL of the moderated image.
`storedUrl`	String	`http://www.aliyundoc.com`	The OSS URL where image evidence is stored. Returned only when the evidence storage feature is enabled and the image matches the configured rule.
`extras`	JSONObject	—	Additional information. When `ad` is specified in `scenes`, this field includes `hitLibInfo` — an array describing custom text library matches.
`results`	JSONArray	—	The moderation results, one element per specified scene. For the structure, see result.

result

Parameter	Type	Example	Description
`scene`	String	`porn`	The moderation scenario. Matches the value specified in `scenes`.
`label`	String	`sexy`	The category of the moderation result. See Label values by scene.
`sublabel`	String	`porn`	The subcategory of the result. Returned for `porn` and `terrorism` scenes only. Not returned by default.
`suggestion`	String	`block`	The recommended action. Valid values: `pass` (no action needed), `review` (requires manual review), `block` (contains violations; delete or block). Use `suggestion`, `label`, and `sublabel` together to determine the appropriate action.
`rate`	Float	`91.54`	The confidence score, from 0 to 100. A higher score indicates higher confidence. For `pass` results, a higher score means the content is more likely normal; for `review` or `block` results, a higher score means violations are more likely present.
`frames`	JSONArray	—	Frame URLs for truncated long images or GIF images. Each element contains `rate` (confidence score) and `url` (temporary URL, valid for 5 minutes).
`hintWordsInfo`	JSONArray	—	The terms matched by violation text detected in the image. Returned for `ad` scene only. Each element contains `context` (the matched term).
`qrcodeData`	StringArray	`["http://www.aliyundoc.com/01ZZOliO"]`	The decoded URLs or text from detected QR codes. Returned for `qrcode` scene only.
`qrcodeLocations`	JSONArray	—	The coordinates of detected QR codes. For the structure, see qrcodeLocation.
`programCodeData`	JSONArray	—	The location information of detected mini program codes. Returned for `qrcode` scene only, when mini program code detection is enabled. For the structure, see programCodeData.
`logoData`	JSONArray	—	The information about detected logos. Returned for `logo` scene only. For the structure, see logoData.
`sfaceData`	JSONArray	—	The information about faces detected in terrorist content. Returned for `terrorism` scene only. For the structure, see sfaceData.
`ocrData`	Array	`["Haokan"]`	The full text detected in the image by OCR. Not returned by default.

Label values by scene

Scene	Labels
`porn`	`normal` (normal), `sexy` (sexy content), `porn` (pornographic content)
`terrorism`	`normal`, `bloody` (bloody content), `explosion` (explosion and smoke), `outfit` (special costume), `logo` (special logo), `weapon`, `politics` (political content), `violence`, `crowd`, `parade`, `carcrash` (car crash), `flag`, `location` (landmark), `drug`, `gamble` (gambling), `others`
`ad`	`normal`, `ad` (other ads), `politics` (political text), `porn` (pornographic text), `abuse` (abusive text), `terrorism` (terrorist text), `contraband` (prohibited text), `spam` (junk text), `npx` (overlay ad), `qrcode` (QR code), `programCode` (mini program code)
`qrcode`	`normal`, `qrcode` (QR code), `programCode` (mini program code)
`live`	`normal`, `meaningless` (blank or empty screen), `PIP` (Picture-in-Picture), `smoking`, `drivelive` (streaming while driving), `drug`, `gamble` (gambling)
`logo`	`normal`, `TV` (logo of banned media), `trademark`

qrcodeLocation

Parameter	Type	Example	Description
`x`	Float	`11.0`	The distance from the left edge of the QR code area to the y-axis. Origin: upper-left corner of the image. Unit: pixels.
`y`	Float	`0.0`	The distance from the top edge of the QR code area to the x-axis. Origin: upper-left corner of the image. Unit: pixels.
`w`	Float	`402.0`	The width of the QR code area. Unit: pixels.
`h`	Float	`413.0`	The height of the QR code area. Unit: pixels.
`qrcode`	String	`http://www.aliyundoc.com/0.ZZOliO`	The URL that the detected QR code points to.

programCodeData

Parameter	Type	Example	Description
`x`	Float	`11.0`	The distance from the left edge of the mini program code area to the y-axis. Origin: upper-left corner of the image. Unit: pixels.
`y`	Float	`0.0`	The distance from the top edge of the mini program code area to the x-axis. Origin: upper-left corner of the image. Unit: pixels.
`w`	Float	`402.0`	The width of the mini program code area. Unit: pixels.
`h`	Float	`413.0`	The height of the mini program code area. Unit: pixels.

logoData

Parameter	Type	Example	Description
`type`	String	`TV`	The type of the detected logo. `TV` indicates a logo of banned media.
`name`	String	`xxx TV`	The name of the detected logo.
`x`	Float	`140`	The distance from the left edge of the logo area to the y-axis. Origin: upper-left corner of the image. Unit: pixels.
`y`	Float	`68`	The distance from the top edge of the logo area to the x-axis. Origin: upper-left corner of the image. Unit: pixels.
`w`	Float	`106`	The width of the logo area. Unit: pixels.
`h`	Float	`106`	The height of the logo area. Unit: pixels.

sfaceData

Parameter	Type	Example	Description
`x`	Float	`49`	The distance from the left edge of the detected face area to the y-axis. Origin: upper-left corner of the image. Unit: pixels.
`y`	Float	`39`	The distance from the top edge of the detected face area to the x-axis. Origin: upper-left corner of the image. Unit: pixels.
`w`	Float	`97`	The width of the detected face area. Unit: pixels.
`h`	Float	`131`	The height of the detected face area. Unit: pixels.
`faces`	JSONArray	—	The recognized faces in this area. Each element contains: `name` (the person's name), `rate` (confidence score, 0–100), and `id` (the face ID).

hitLibInfo

Parameter	Type	Example	Description
`context`	String	`Haokan`	The custom term matched by the detected text.
`libCode`	String	`123456`	The code of the library containing the matched term.
`libName`	String	`abc`	The name of the library containing the matched term.

Examples

Request example

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

{
    "scenes": [
        "porn",
        "terrorism",
        "ad",
        "live",
        "qrcode",
        "logo"
    ],
    "tasks": [
        {
            "dataId": "uuid-xxxx-xxxx-1234",
            "url": "http://www.aliyundoc.com/xxx.jpg"
        }
    ]
}

Response example

{
    "msg": "OK",
    "code": 200,
    "requestId": "69B41AE8-1234-1234-1234-12D395695D2D",
    "data": [
        {
            "msg": "OK",
            "code": 200,
            "dataId": "cfd33235-71a4-468b-8137-a5ffe323****",
            "taskId": "img4wlJcb7p4wH4lAP3111111-123456",
            "url": "http://www.aliyundoc.com/xxx.jpg",
            "extras": {},
            "results": [
                {
                    "scene": "porn",
                    "label": "sexy",
                    "rate": 99.63,
                    "suggestion": "block"
                },
                {
                    "scene": "terrorism",
                    "label": "politics",
                    "rate": 91.54,
                    "suggestion": "block",
                    "sfaceData": [
                        {
                            "x": 49,
                            "y": 39,
                            "w": 97,
                            "h": 131,
                            "faces": [
                                {
                                    "id": "AliFace_0123****",
                                    "name": "Hit name",
                                    "rate": 91.54
                                }
                            ]
                        }
                    ]
                },
                {
                    "scene": "ad",
                    "label": "ad",
                    "rate": 99.91,
                    "suggestion": "block",
                    "extras": {
                        "qrcodes": "http://www.aliyundoc.com/0.ZZOliO",
                        "npx": "72.01",
                        "hitCustomLibCode": "8012345000",
                        "hitCustomLibName": "Name of the custom image library",
                        "hitLibInfo": [
                            {
                                "context": "Hit text",
                                "libCode": "123456",
                                "libName": "Name of the custom text library"
                            }
                        ]
                    },
                    "frames": [
                        {
                            "rate": 89.85,
                            "url": "http://www.aliyundoc.com/xxx-0.jpg"
                        },
                        {
                            "rate": 68.06,
                            "url": "http://www.aliyundoc.com/xxx-1.jpg"
                        }
                    ],
                    "programCodeData": [
                        {
                            "x": 11.0,
                            "y": 0.0,
                            "w": 402.0,
                            "h": 413.0
                        }
                    ]
                },
                {
                    "scene": "live",
                    "label": "drug",
                    "rate": 99.91,
                    "suggestion": "block"
                },
                {
                    "scene": "qrcode",
                    "label": "qrcode",
                    "rate": 99.91,
                    "suggestion": "review",
                    "qrcodeData": [
                        "http://www.aliyundoc.com/01ZZOliO"
                    ]
                },
                {
                    "scene": "logo",
                    "label": "TV",
                    "rate": 99.9,
                    "suggestion": "block",
                    "logoData": [
                        {
                            "name": "xxx TV",
                            "type": "TV",
                            "x": 140,
                            "y": 68,
                            "w": 106,
                            "h": 106
                        }
                    ]
                }
            ]
        }
    ]
}