Video File Moderation Enhanced API - AI Guardrails - Alibaba Cloud Documentation Center

Submits video files for asynchronous content moderation and retrieves results using the VideoModeration and VideoModerationResult API operations.

Prerequisites

Before you begin, make sure you have:

An Alibaba Cloud account. Register here.
AI Guardrails activated with pay-as-you-go billing. Activate the service. Activation is free; you are billed based on actual usage.
An AccessKey created via Resource Access Management (RAM). Create an AccessKey. If you use a RAM user's AccessKey, grant the AliyunYundunGreenWebFullAccess permission to that user. Grant permissions.
Moderation rules configured in the AI Guardrails console. Required before your first API call.

For SDK setup and integration samples, see Video Moderation 2.0 SDK and integration guide.

How it works

All video moderation tasks are processed asynchronously:

Call VideoModeration to submit a video file. The operation returns a TaskId.
After 30 seconds, call VideoModerationResult with the TaskId to retrieve results.
Alternatively, include a callback URL in the submission request to receive results automatically when moderation is complete.

Detection results are retained for 24 hours. After that, the task ID expires and results are no longer accessible.

Submit a moderation task

Submits an asynchronous video file moderation task and returns a task ID for polling results.

API operation: VideoModeration

Endpoints

Region	Public endpoint	VPC endpoint	Supported services
Singapore	green-cip.ap-southeast-1.aliyuncs.com	green-cip-vpc.ap-southeast-1.aliyuncs.com	videoDetection_global, videoDetectionByVL_global
US (Virginia)	green-cip.us-east-1.aliyuncs.com	green-cip-vpc.us-east-1.aliyuncs.com	videoDetection_global
US (Silicon Valley)	green-cip.us-west-1.aliyuncs.com	Not available
Germany (Frankfurt)	green-cip.eu-central-1.aliyuncs.com	Not available

Rate limits

QPS limit: 100 requests per second per account
Concurrent task limit: 50 tasks

If these limits are exceeded, throttling is triggered. To increase the concurrent task limit, contact your account manager.

Debugging

Debug the operation online using Alibaba Cloud OpenAPI. You can view sample code, SDK dependencies, and parameter details.

Important

Online debugging calls the API using your current account and is included in your billable usage.

Billing

Charges are based on the detection policies you configure:

Video frames: number of frames × unit price per service (you can select multiple services)
Audio detection: video duration × unit price for audio detection

Only requests that return code 200 or 280 are billed. For pricing details, see Activate the serviceBilling.

Request parameters

Name	Type	Required	Example	Description
Service	String	Yes	videoDetection_global	The moderation service type. Valid values: videoDetection_global: Video file detection videoDetectionByVL_global: Video file detection_Large model version
ServiceParameters	JSONString	Yes		The moderation parameters as a JSON string. See ServiceParameters.

Name

Type

Required

Example

Description

Service

String

Yes

videoDetection_global

The moderation service type. Valid values:

videoDetection_global: Video file detection
videoDetectionByVL_global: Video file detection_Large model version

ServiceParameters

JSONString

Yes

The moderation parameters as a JSON string. See ServiceParameters.

ServiceParameters

The video source is required. Use one of the following three methods to provide the video file:

URL: Set the url parameter to a publicly accessible HTTP or HTTPS URL.
OSS authorization: Set ossBucketName, ossObjectName, and ossRegionId. Before using an internal OSS address, grant the required permissions on the Cloud Resource Access Authorization page.
Local file upload: Available via the SDK only. The file is stored for 30 minutes. For code examples, see Enhanced Video Moderation 2.0 SDK and access guide.

Name	Type	Required	Example	Description
url	String	Yes (for URL method)	`http://www.aliyundoc.com/a.flv`	The URL of the video to moderate. Must be accessible over the public network, or use an OSS internal network address in the same region. The URL cannot contain Chinese characters and must be no longer than 2,048 characters. One URL per request.
ossBucketName	String	Yes (for OSS method)	`bucket_01`	The name of the authorized OSS bucket.
ossObjectName	String	Yes (for OSS method)	`20240307/07/28/test.flv`	The path and filename of the video in the OSS bucket.
ossRegionId	String	Yes (for OSS method)	`cn-shanghai`	The region where the OSS bucket is located.
callback	String	No	`http://www.aliyundoc.com`	The URL to receive moderation results. Supports HTTP and HTTPS. The endpoint must accept POST requests with UTF-8 encoding and handle the `checksum` and `content` form parameters. If omitted, poll for results using `VideoModerationResult`.
seed	String	No	`abc****`	A random string used to sign callback notifications. Can contain letters, digits, and underscores, up to 64 characters. Required if `callback` is specified.
cryptType	String	No	`SHA256`	The signing algorithm for callback notifications. Valid values: SHA256 (default) and SM3 (returns a hexadecimal string of lowercase letters and digits).
dataId	String	No	`videoId****`	A custom identifier for this request, used to correlate your business data with moderation results. Can contain uppercase letters, lowercase letters, digits, underscores (`_`), hyphens (`-`), and periods (`.`), up to 128 characters.
offline	String	No	`false`	Specifies whether to use offline (nearline) processing. Valid values: false (default, real-time; tasks exceeding the concurrency limit are rejected) and true (tasks are queued and processed within 24 hours). Offline mode is supported in the China (Beijing), China (Shanghai), and China (Hangzhou) regions.
referer	String	No	`www.aliyun.com`	The HTTP Referer header value, for use cases such as hotlink protection. Up to 256 characters.

Callback verification:

When your callback endpoint receives a request from AI Guardrails, verify authenticity using the checksum parameter:

checksum: A hash of the concatenated string user UID + seed + content, computed using the algorithm specified by cryptType (default: SHA256). The user UID is your Alibaba Cloud account ID, found in the Alibaba Cloud Management Console. Use your account UID, not a RAM user UID.
content: A JSON string containing the moderation result. Parse it to a JSON object. The structure matches the response from VideoModerationResult.

If your endpoint returns any HTTP status code other than 200, AI Guardrails retries up to 16 times. After 16 failed retries, it stops sending the result.

Default configurations

If you haven't configured custom rules in the console, the following defaults apply:

Service	Default configuration
videoDetection_global	Snapshot frequency: 1 frame/sec; Frame service: baselineCheck_global; Audio detection: enabled; Audio service: audio_multilingual_global; Returns: flagged results only
videoDetectionByVL_global	Snapshot frequency: 1 frame/sec; Frame service: postImageCheckByVL_global; Audio detection: enabled; Audio service: audio_multilingual_global; Returns: flagged results only

To configure custom rules (snapshot method, snapshot frequency, image moderation rules, audio moderation rules, and result scope), see Console user guide.

Video requirements

Protocols: HTTP and HTTPS
Formats: AVI, FLV, MP4, MPG, ASF, WMV, MOV, WMA, RMVB, RM, FLASH, TS, M3U8
Size limit: 500 MB per video. To moderate larger videos, split them into segments or contact your account manager to increase the limit.
Accessibility: Detection time depends on video download speed. Store video files in a stable, reliable location. Alibaba Cloud Object Storage Service (OSS) is recommended.

Response parameters

Name	Type	Example	Description
Code	Integer	200	The status code. See Status codes.
Data.TaskId	String	AAAAA-BBBBB	The task ID. Use this to retrieve moderation results via `VideoModerationResult`.
Data.DataId	String	dataId0307	The data ID from your request.
Message	String	OK	The response message.
RequestId	String	ABCD1234-1234-1234-1234-123****	The request ID.

Example

Request:

{
    "Service": "videoDetection_global",
    "ServiceParameters": {
        "taskId": "abcd****"
    }
}

{
    "Service": "videoDetection_global",
    "ServiceParameters": {
        "url": "http://www.aliyundoc.com/a.flv",
        "dataId": "videoId****"
    }
}

Response:

{
    "Message": "OK",
    "Code": 200,
    "Data": {
        "TaskId": "AAAAA-BBBBB",
        "DataId": "videoId****"
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

Get moderation results

Retrieves the frame and audio detection results for a submitted video moderation task.

API operation: VideoModerationResult

This operation is not billable. Query results at least 30 seconds after submitting the task. Results are automatically deleted after 24 hours.

Rate limits

QPS limit: 100 requests per second per account. If exceeded, throttling is triggered.

Debugging

Debug the VideoModerationResult operation online using Alibaba Cloud OpenAPI.

Request parameters

Name	Type	Required	Example	Description
Service	String	Yes	videoDetection_global	The moderation service type. Must match the value used when submitting the task.
ServiceParameters	JSONString	Yes		See below.

ServiceParameters:

Name	Type	Required	Example	Description
taskId	String	Yes	`abcd****`	The task ID returned by `VideoModeration`. One task ID per request.

Response parameters

Name	Type	Example	Description
RequestId	String	ABCD1234-1234-1234-1234-123****	The request ID.
Code	String	200	The status code. See Status codes.
Message	String	OK	The response message.
Data	Object		The detection results. See Data.

Data

Name	Type	Example	Description
DataId	String	videoId****	The data ID from the original request.
TaskId	String	AAAAA-BBBBB-2024-0307	The task ID.
RiskLevel	String	high	The overall risk level, determined by combining frame and audio analysis. Valid values: high (block immediately), medium (manual review), low (process only when high recall is required; otherwise treat as no risk), none (no risk detected). Configure risk score thresholds in the AI Guardrails console.
FrameResult	JSONObject		Frame detection results. See FrameResult. A code of 280 means detection is in progress; 200 means detection is complete. In-progress results include data from detection start to the current time.
AudioResult	JSONObject		Audio detection results. See AudioResult.

FrameResult

Name	Type	Example	Description
FrameNum	Integer	200	The number of video frames returned.
RiskLevel	String	high	The risk level across all video frames. Valid values: high, medium, low, none.
FrameSummarys	JSONArray		Label summary across all frames. See FrameSummarys.
Frames	JSONArray		Details of frames with flagged labels. See Frames.

FrameSummarys

Name	Type	Example	Description
Label	String	violent_armedForces	The flagged label.
Description	String	Suspected to contain firework-type content elements	A human-readable description of the label. Subject to change — use `Label` for programmatic processing, not `Description`.
LabelSum	Integer	8	The number of frames that matched this label.

Frames

Name	Type	Example	Description
TempUrl	String	`http://www.aliyundoc.com/test.jpg`	A temporary URL to the video frame image, valid for 30 minutes. If video evidence storage is enabled, the OSS URL of the stored frame is returned instead.
Offset	Float	50.5	The timestamp of the frame from the start of the video, in seconds.
RiskLevel	String	high	The risk level of this frame, based on configured risk score thresholds. Valid values: high, medium, low, none.
Results	JSONArray		Per-service detection results for this frame. See Results.

Results

Name	Type	Example	Description
Service	String	baselineCheck_global	The detection service that processed this frame.
Result	Array		Detection labels and scores for this frame. See Result.

Result

Name	Type	Example	Description
Label	String	violent_explosion	The detection label. A single frame can return multiple labels. For supported labels, see General baseline detection (baselineCheck_global) supported labels .
Confidence	Float	81.22	The confidence score, ranging from 0 to 100 (two decimal places).
Description	String	Suspected to contain firework-related content elements	A human-readable description of the label. Subject to change — use `Label` for programmatic processing, not `Description`.

AudioResult

Name	Type	Example	Description
RiskLevel	String	high	The risk level across all audio segments. Valid values: high, medium, low, none.
AudioSummarys	JSONArray		Label summary across all audio. See AudioSummarys.
SliceDetails	JSONArray		Per-sentence transcription and detection details. See SliceDetails.

AudioSummarys

Name	Type	Example	Description
Label	String	profanity	The flagged audio label.
LabelSum	Integer	8	The number of audio segments that matched this label.

SliceDetails

Name	Type	Example	Description
StartTime	Integer	0	The start time of the audio segment, in seconds.
EndTime	Integer	4065	The end time of the audio segment, in seconds.
StartTimestamp	Integer	1678854649720	The start timestamp of the segment, in milliseconds.
EndTimestamp	Integer	1678854649720	The end timestamp of the segment, in milliseconds.
Text	String	Disgusting	The transcribed text from the audio segment.
Url	String	`https://aliyundoc.com/test.wav`	A temporary URL to the audio segment file, valid for 30 minutes. Save a copy before the URL expires.
Labels	String	political_content,xxxx	Comma-separated list of flagged labels. Valid values: ad (advertisements), violence (violent and terrorist content), political_content (political content), specified_speaking (specific voices), specified_lyrics (specific songs), sexual_content (pornographic content), sexual_sounds (sexually suggestive sounds), contraband (contraband-related content), profanity (abusive content), religion (religious content), cyberbullying (cyberbullying content), negative_content (inappropriate content), nontalk (silent audio), C_customized (custom library match).
RiskLevel	String	high	The risk level of this audio segment. Valid values: high, medium, low, none.
RiskWords	String	AAA,BBB,CCC	Comma-separated list of matched risk words.
RiskTips	String	pornography_vulgar_words,pornography_description	Comma-separated detailed labels.
Extend	String	`{"riskTips":"pornography_vulgar_words","riskWords":"sexual_services"}`	Reserved field.

Examples

Request:

Response (frame detection only):

{
    "Code": 200,
    "RequestId": "25106421-XXXX-XXXX-XXXX-15DA5AAAC546",
    "Message": "success finished",
    "Data": {
        "DataId": "ABCDEF-TESTDATAID",
        "TaskId": "AAAAA-BBBBB-2024-0307-0728",
        "RiskLevel": "medium",
        "AudioResult": {
            "AudioSummarys": [
                {
                    "Label": "sexual_sounds",
                    "LabelSum": 3
                }
            ],
            "RiskLevel": "high",
            "SliceDetails": [
                {
                    "EndTime": 60,
                    "EndTimestamp": 1698912813192,
                    "Labels": "",
                    "RiskLevel": "none",
                    "StartTime": 30,
                    "StartTimestamp": 1698912783192,
                    "Text": "AI Guardrails",
                    "Url": "http://abc.oss-ap-southeast-1.aliyuncs.com/test.wav"
                },
                {
                    "EndTime": 30,
                    "EndTimestamp": 1698912813192,
                    "Extend": "{\"customizedWords\":\"service\",\"customizedLibs\":\"test\"}",
                    "Labels": "C_customized",
                    "RiskLevel": "high",
                    "StartTime": 0,
                    "StartTimestamp": 1698912783192,
                    "Text": "Welcome to Alibaba Cloud AI Guardrails service",
                    "Url": "http://abc.oss-ap-southeast-1.aliyuncs.com/test.wav"
                }
            ]
        },
        "FrameResult": {
            "FrameNum": 2,
            "FrameSummarys": [
                {
                    "Label": "violent_explosion",
                    "Description": "Suspected to contain firework-type content elements",
                    "LabelSum": 8
                },
                {
                    "Label": "sexual_cleavage",
                    "Description": "Suspected to contain body exposure or sexually suggestive content",
                    "LabelSum": 8
                }
            ],
            "RiskLevel": "medium",
            "Frames": [
                {
                    "Offset": 1,
                    "RiskLevel": "none",
                    "Results": [
                        {
                            "Result": [
                                {
                                    "Label": "nonLabel",
                                    "Description": "No risk detected"
                                }
                            ],
                            "Service": "baselineCheck_global"
                        }
                    ],
                    "TempUrl": "http://abc.oss-ap-southeast-1.aliyuncs.com/test1.jpg"
                },
                {
                    "Offset": 2,
                    "RiskLevel": "medium",
                    "Results": [
                        {
                            "Result": [
                                {
                                    "Confidence": 1,
                                    "Label": "sexual_cleavage",
                                    "Description": "Suspected to contain body exposure or sexually suggestive content"
                                },
                                {
                                    "Confidence": 74.1,
                                    "Label": "violent_explosion",
                                    "Description": "Suspected to contain firework-type content elements"
                                }
                            ],
                            "Service": "baselineCheck_global"
                        }
                    ],
                    "TempUrl": "http://abc.oss-ap-southeast-1.aliyuncs.com/test2.jpg"
                }
            ]
        }
    }
}

Response (frame and audio detection):

{
    "Code": 200,
    "RequestId": "25106421-XXXX-XXXX-XXXX-15DA5AAAC546",
    "Message": "success finished",
    "Data": {
        "DataId": "ABCDEF-TESTDATAID",
        "TaskId": "AAAAA-BBBBB-2024-0307-0728",
        "RiskLevel": "medium",
        "AudioResult": {
            "AudioSummarys": [
                {
                    "Label": "sexual_sounds",
                    "LabelSum": 3
                }
            ],
            "RiskLevel": "high",
            "SliceDetails": [
                {
                    "EndTime": 60,
                    "EndTimestamp": 1698912813192,
                    "Labels": "",
                    "RiskLevel": "none",
                    "StartTime": 30,
                    "StartTimestamp": 1698912783192,
                    "Text": "AI Guardrails",
                    "Url": "http://abc.oss-ap-southeast-1.aliyuncs.com/test.wav"
                },
                {
                    "EndTime": 30,
                    "EndTimestamp": 1698912813192,
                    "Extend": "{\"customizedWords\":\"service\",\"customizedLibs\":\"test\"}",
                    "Labels": "C_customized",
                    "RiskLevel": "high",
                    "StartTime": 0,
                    "StartTimestamp": 1698912783192,
                    "Text": "Welcome to Alibaba Cloud AI Guardrails service",
                    "Url": "http://abc.oss-ap-southeast-1.aliyuncs.com/test.wav"
                }
            ]
        },
        "FrameResult": {
            "FrameNum": 2,
            "FrameSummarys": [
                {
                    "Label": "violent_explosion",
                    "Description": "Suspected to contain firework-type content elements",
                    "LabelSum": 8
                },
                {
                    "Label": "sexual_cleavage",
                    "Description": "Suspected to contain body exposure or sexually suggestive content",
                    "LabelSum": 8
                }
            ],
            "RiskLevel": "medium",
            "Frames": [
                {
                    "Offset": 1,
                    "RiskLevel": "none",
                    "Results": [
                        {
                            "Result": [
                                {
                                    "Label": "nonLabel",
                                    "Description": "No risk detected"
                                }
                            ],
                            "Service": "baselineCheck_global"
                        }
                    ],
                    "TempUrl": "http://abc.oss-ap-southeast-1.aliyuncs.com/test1.jpg"
                },
                {
                    "Offset": 2,
                    "RiskLevel": "medium",
                    "Results": [
                        {
                            "Result": [
                                {
                                    "Confidence": 1,
                                    "Label": "sexual_cleavage",
                                    "Description": "Suspected to contain body exposure or sexually suggestive content"
                                },
                                {
                                    "Confidence": 74.1,
                                    "Label": "violent_explosion",
                                    "Description": "Suspected to contain firework-type content elements"
                                }
                            ],
                            "Service": "baselineCheck_global"
                        }
                    ],
                    "TempUrl": "http://abc.oss-ap-southeast-1.aliyuncs.com/test2.jpg"
                }
            ]
        }
    }
}

Status codes

Only requests that return code 200 or 280 are billed.

Code	Description
200	Request successful or detection complete.
280	Detection in progress.
288	Queued for processing in nearline mode.
400	Request parameters are empty.
401	Request parameters are invalid.
402	A parameter exceeds the allowed length. Check and correct the parameter.
403	QPS limit exceeded. Reduce the number of concurrent requests.
404	Failed to download the video. Check the video URL and retry.
405	Video download timed out. The video may be inaccessible. Check the URL and retry.
406	Video file too large. Reduce the video size and retry.
407	Video format not supported. Use a supported format and retry.
408	Account lacks permission to call this API. The service may not be activated, the account may have an overdue payment, or the required permissions have not been granted.
409	TaskId not found. The task result may have expired (results are retained for 24 hours only).
480	Concurrent ingest endpoint limit exceeded. Reduce the number of concurrent requests.
500	System error.

AI Guardrails:Video File Moderation 2.0 API

Prerequisites

How it works

Submit a moderation task

Endpoints

Rate limits

Debugging

Billing

Request parameters

ServiceParameters

Default configurations

Video requirements

Response parameters

Example

Get moderation results

Rate limits

Debugging

Request parameters

Response parameters

Data

FrameResult

FrameSummarys

Frames

Results

Result

AudioResult

AudioSummarys

SliceDetails

Examples

Status codes

What's next