Call the /green/video/syncscan operation to moderate video content - AI Guardrails

Moderates video content by analyzing uploaded video frames for pornographic, terrorist and political, undesirable, logo, and text violation content.

Operation description

Endpoint: POST /green/video/syncscan

This operation accepts up to 100 detection tasks per request, each containing up to 200 video frames. Submit frames as HTTP or HTTPS URLs — the operation downloads and analyzes each frame synchronously and returns results in the same response.

To moderate a video by URL instead of individual frames, use the asynchronous video detection operation.

For details on constructing HTTP requests, see Request structure. To use a pre-built client, see SDK overview.

Detection scenarios

Scenario	`scenes` value	Result labels
Pornography detection	`porn`	`normal`, `porn`
Terrorism and political content	`terrorism`	`normal`, `terrorism`
Inappropriate video content	`live`	`normal`, `live`
Logo detection	`logo`	`normal`, `logo`
Violations in video, images, and text	`ad`	`normal`, `ad`

Video and Audio Content Violations is available only through the asynchronous video detection operation. This scenario detects non-compliant information in the audio of a video and returns the following result categories: Normal, Spam, Ad, Political, Terrorism, Abuse, Pornographic, Flooding, Contraband, Custom (such as hits on custom keywords). By default, the supported language is Chinese. To detect English content, contact your account manager.

Billing

Charges apply per scenario per frame analyzed. When multiple scenarios are specified, each scenario is billed separately:

Total fee = Number of frames analyzed per scenario × Unit price per scenario

Usage notes

Video frame requirements

URLs must use HTTP or HTTPS.
Supported formats: PNG, JPG, JPEG, BMP, GIF, WEBP.
Maximum frame size: 10 MB.
Minimum recommended resolution: 256 × 256 pixels (smaller frames may reduce moderation accuracy).
Use a reliable storage service such as Object Storage Service (OSS) or Content Delivery Network (CDN) to minimize download latency. Response time varies based on frame download speed.

QPS limits

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

Request parameters

Parameter	Type	Required	Example	Description
`bizType`	String	No	`default`	The business scenario. Create and manage scenarios in the Content Moderation console. For details, see Customize policies for machine-assisted moderation.
`scenes`	StringArray	Yes	`["porn"]`	The moderation scenarios to run. Valid values: `porn`, `terrorism`, `live`, `logo`, `ad`. Multiple values are allowed.
`tasks`	JSONArray	Yes	—	The detection tasks. Maximum: 100 elements per request. Each element follows the `task` structure below. To submit 100 concurrent tasks, set the concurrency limit to more than 100.

task

Parameter	Type	Required	Example	Description
`dataId`	String	No	`videoId****`	An identifier for the moderation object. Accepted characters: letters, digits, underscores (`_`), hyphens (`-`), and periods (`.`). Maximum length: 128 characters. The value is echoed in the response.
`frames`	JSONArray	Yes	—	The video frames to moderate. Maximum: 200 frames per task. Each element follows the `frame` structure below.
`framePrefix`	String	No	—	A URL prefix prepended to each `frame.url` value. The complete frame URL is constructed as `framePrefix + frame.url`.
`clientInfo`	JSONObject	No	`{"userId":"12023****","userNick":"Mike","userType":"others"}`	Client metadata. For the full structure, see the "Common request parameters" section of Common parameters. When set, this value takes priority over the global `clientInfo` parameter.

frame (request)

Parameter	Type	Required	Example	Description
`url`	String	Yes	`http://www.aliyundoc.com/test0001.jpg`	The publicly accessible HTTP or HTTPS URL of the video frame. Maximum length: 2,048 characters.
`offset`	Integer	No	`10`	The timestamp of the frame within the video, relative to the start. Unit: seconds.

Response elements

Parameter	Type	Example	Description
`code`	Integer	`200`	The HTTP status code for the overall request. For details, see Common error codes.
`msg`	String	`OK`	The response message for the overall request.
`requestId`	String	`requestID****`	The request ID.
`data`	JSONArray	—	The per-task moderation results. Each element follows the per-task structure below.

Per-task response

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	`videoId****`	The identifier from the request. Returned only if `dataId` was set in the request.
`taskId`	String	`taskId****`	The detection task ID.
`results`	JSONArray	—	The moderation results, one element per scenario. Each element follows the `result` structure below. Populated when `code` is `200`.

result

Parameter	Type	Example	Description
`scene`	String	`porn`	The detection scenario. Matches the value specified in the request. Valid values: `porn`, `terrorism`, `live`, `logo`, `ad`.
`label`	String	`porn`	The result category for this scenario. See Detection scenarios for the full list of labels per scenario.
`sublabel`	String	`porn`	A subcategory of the result. Returned only for `porn` and `terrorism` scenarios, and only when available. Not returned by default.
`suggestion`	String	`block`	The recommended action. Valid values: `pass` (content is normal; no action required), `review` (uncertain; manual review required), `block` (non-compliant; delete or restrict the content).
`rate`	Float	`99.2`	The confidence score for the result. Range: 0–100. A higher score with `suggestion: pass` indicates higher confidence that the content is normal. A higher score with `suggestion: review` or `block` indicates higher confidence that the content contains violations. Use `suggestion`, `label`, and `sublabel` to determine the moderation outcome — do not use `rate` alone.
`frames`	JSONArray	—	The frames that triggered a non-compliant result. Each element follows the `frame` (response) structure below.
`extras`	JSONObject	—	Additional context. In the `ad` scenario, may contain `hitLibInfo` if the content matches a custom text library.
`hintWordsInfo`	JSONArray	—	The risk keywords that were matched. Returned only in the `ad` scenario. Each element follows the `hintWordsInfo` structure below.
`logoData`	JSONArray	—	The detected logo details. Returned only in the `logo` scenario. Each element follows the `logoData` structure below.
`sfaceData`	JSONArray	—	The detected face details from terrorism and political content. Returned only in the `terrorism` scenario. Each element follows the `sfaceData` structure below.

frame (response)

Parameter	Type	Example	Description
`url`	String	`http://www.aliyundoc.com/test0001.jpg`	The HTTP or HTTPS URL of the frame. Maximum length: 2,048 characters.
`offset`	Integer	`50`	The timestamp of the frame within the video. Unit: seconds.
`label`	String	`porn`	The result category for this frame.
`rate`	Float	`99.1`	The confidence score for this frame. Range: 0–100. Do not use this score in your moderation logic.

logoData

Parameter	Type	Example	Description
`type`	String	`TV`	The type of the detected logo. Valid value: `TV` (TV station logo).
`name`	String	`xxx units`	The name of the detected logo.
`x`	Float	`140`	The x-coordinate of the upper-left corner of the logo region. Origin: upper-left corner of the frame. Unit: pixels.
`y`	Float	`68`	The y-coordinate of the upper-left corner of the logo region. Unit: pixels.
`w`	Float	`106`	The width of the logo region. Unit: pixels.
`h`	Float	`106`	The height of the logo region. Unit: pixels.

sfaceData

Parameter	Type	Example	Description
`x`	Float	`49`	The x-coordinate of the upper-left corner of the detected face region. Origin: upper-left corner of the frame. Unit: pixels.
`y`	Float	`39`	The y-coordinate of the upper-left corner of the face region. Unit: pixels.
`w`	Float	`97`	The width of the face region. Unit: pixels.
`h`	Float	`131`	The height of the face region. Unit: pixels.
`faces`	JSONArray	`[{"name":"Hit Person Name","rate":91.54,"id":"AliFace_0123****"}]`	Details of the detected faces. Each element contains: `name` (String, the name of the matched person), `rate` (Float, confidence score from 0 to 100), and `id` (String, the face ID).

hitLibInfo

Parameter	Type	Example	Description
`context`	String	`Haokan Video`	The text from the custom library that was matched.
`libCode`	String	`123456`	The code of the custom library that contains the matched text.
`libName`	String	`abc`	The name of the custom library that contains the matched text.

hintWordsInfo

Parameter	Type	Example	Description
`context`	String	`Good video`	The risk keyword that was matched.

Examples

Request

POST http(s)://[Endpoint]/green/video/syncscan
<Common request parameters>

{
    "scenes": [
        "porn"
    ],
    "tasks": [
        {
            "dataId": "videoId****",
            "frames": [
                {
                    "offset": 10,
                    "url": "http://www.aliyundoc.com/0B860000586C0A0300038A0460000"
                },
                {
                    "offset": 20,
                    "url": "http://www.aliyundoc.com/0B860000586C0A0300038A0460001"
                },
                {
                    "offset": 30,
                    "url": "http://www.aliyundoc.com/0B860000586C0A0300038A0460002"
                },
                {
                    "offset": 40,
                    "url": "http://www.aliyundoc.com/0B860000586C0A0300038A0460003"
                },
                {
                    "offset": 50,
                    "url": "http://www.aliyundoc.com/0B860000586C0A0300038A0460003"
                },
                {
                    "offset": 60,
                    "url": "http://www.aliyundoc.com/0B860000586C0A0300038A046000x"
                }
            ]
        }
    ]
}

Response

{
    "code": 200,
    "msg": "OK",
    "requestId": "requestID****",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "videoId****",
            "taskId": "taskId****",
            "results": [
                {
                    "label": "porn",
                    "rate": 99.2,
                    "scene": "porn",
                    "suggestion": "block",
                    "frames": [
                        {
                            "offset": 50,
                            "url": "http://www.aliyundoc.comm/0B860000586C0A0300038A0460003",
                            "label": "porn",
                            "rate": 99.1
                        }
                    ]
                }
            ]
        }
    ]
}

In this example, the operation analyzed 6 frames from one video in the porn scenario. One frame (at the 50-second offset) triggered a block recommendation with a confidence score of 99.2.