Live Video Stream Moderation API v2.0 - AI Guardrails - Alibaba Cloud Documentation Center

Submits, queries, and cancels asynchronous moderation jobs for live video streams, detecting risky content in video frames and audio.

This document covers three API operations:

Operation	Purpose	Billed
	Submit a live stream moderation job	Yes
VideoModerationResult	Query the result of a moderation job	No
VideoModerationCancel	Cancel a running moderation job	No

Prerequisites

Before you begin, ensure that you have:

An Alibaba Cloud account. Register here.
AI Guardrails activated with pay-as-you-go billing enabled. Enable the service. No activation fee is charged.
An AccessKey created in the RAM console. Create an AccessKey. If you use a Resource Access Management (RAM) user, grant the AliyunYundunGreenWebFullAccess permission to that RAM user. Grant permissions.
The Video Moderation SDK v2.0 integrated. SDK and integration guide.

Submit a moderation job

Operation: VideoModeration

Submits an asynchronous moderation job for a live video stream. Results are not returned immediately. Retrieve them using a callback URL or by polling with VideoModerationResult.

Choose your result retrieval method before submitting:

Callback: Specify the callback parameter when submitting. AI Guardrails pushes results to your endpoint as they are detected.
Polling: Omit the callback parameter. Call VideoModerationResult at intervals of at least 30 seconds to retrieve results.

Supported regions and endpoints

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

Billing

Charged based on the moderation policies configured for video frames and audio:

Video frames: number of snapshots x unit price per service. Multiple frame moderation services can be selected and each is billed separately.
Audio: video duration x unit price of the audio moderation feature.

For pricing details, see Billing.

Live stream requirements

Supported protocols: RTMP, HLS, HTTP-FLV, RTSP
Maximum duration: 24 hours per job. Jobs that exceed this limit end automatically.

Default moderation configurations

Configure moderation rules in the AI Guardrails console. If no rules are configured, the following defaults apply:

Service	Default configuration
liveStreamDetection_global	Frame capture: 1 frame/second<br>Frame detection: General baseline detection (`baselineCheck_global`)<br>Audio detection: Enabled (`live_stream_detection_global`)<br>Result filter: Returns only results with detected threats
liveStreamDetectionByVL_global	Frame capture: 1 frame/second<br>Frame detection: Image moderation with large and small models (`postImageCheckByVL`)<br>Audio detection: Enabled (`live_stream_detection_cb`)<br>Result filter: Returns only results with detected threats<br> Note Currently supported only in the Beijing and Shanghai regions. Limited to 10 concurrent ingest endpoints.

QPS limits

QPS limit: 100 per user
Concurrent stream limit: 50 jobs processed simultaneously

If either limit is exceeded, the API call is throttled. To increase your limits, contact your business manager.

Debugging

Debug the VideoModeration API online in Alibaba Cloud OpenAPI to view sample code, SDK dependency information, and a full parameter overview.VideoModerationCancelVideoModerationResultVideoModeration

Important

Online debugging calls the API using your logged-in account. These calls count toward the billable usage of your account.

Request parameters

Name	Type	Required	Example	Description
Service	String	Yes	liveStreamDetection_global	The moderation service to use. Valid values: `liveStreamDetection_global` (standard), `liveStreamDetectionByVL_global` liveStreamDetection_global: live video stream moderation liveStreamDetectionByVL_global: live video stream moderation (large model edition) (large model edition).
ServiceParameters	JSONString	Yes		A JSON string containing the parameters for the moderation service. See the following table.

ServiceParameters

Name	Type	Required	Example	Description
url	String	Yes	http://www.aliyundoc.com/a.flv	The URL of the live stream to moderate. Must be accessible over the Internet, up to 2,048 characters. Cannot contain Chinese characters. Specify only one URL per request.
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 encoded data and the `checksum` and `content` form parameters.<br><br>AI Guardrails sets these parameters as follows:<br>- `checksum`: SHA256 hash of `user UID + seed + content`. Verify the checksum against this value to confirm the result was not tampered with. Note Use your Alibaba Cloud account UID, not a RAM user UID. Find your UID in the Alibaba Cloud Management Console.<br>- `content`: A JSON-formatted string. Parse and deserialize it to obtain the result object. See the response example under Query moderation results.<br><br>After your callback server returns HTTP 200, the result is considered received. For any other status code, AI Guardrails retries up to 16 times. If the result is still not received after 16 retries, it is no longer pushed. Check your callback endpoint status regularly.<br><br>If left blank, use polling to retrieve results.
seed	String	No	abc\\\\	A random string used to sign callback notifications. Can contain letters, digits, and underscores (`_`), up to 64 characters. Required when using a callback.
cryptType	String	No	SHA256	The encryption algorithm for the callback signature. Valid values:<br>- `SHA256` (default): SHA256 algorithm.<br>- `SM3`: HMAC-SM3 algorithm. Returns a hexadecimal string of lowercase letters and digits. For example, encrypting `abc` with SM3 returns `66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0`.
dataId	String	No	videoId\\\\	A custom identifier for the object, up to 128 characters. Supports uppercase letters, lowercase letters, digits, underscores (`_`), hyphens (`-`), and periods (`.`). Use this ID to map results back to your business data.
liveId	String	No	liveId\\\\	An ID for the live stream, used to prevent duplicate moderation jobs. If specified, the system checks whether a job is already running for the same `uid + service + liveId` combination. If one exists, the system returns the `TaskId` of the existing job instead of starting a new one.

Response parameters

Name	Type	Example	Description
Code	Integer	200	The status code. See Status codes.
Data	JSONObject	{"TaskId": "AAAAA-BBBBB"}	The result data, containing the `TaskId` of the submitted job.
Message	String	OK	The response message.
RequestId	String	ABCD1234-1234-1234-1234-123\\\\	The request ID.

Example

Request:

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

Response:

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

Query moderation results

Operation: VideoModerationResult

Queries the results of a live stream moderation job by its TaskId. This operation is free of charge.

Query behavior:

Query no sooner than 30 seconds after submitting the job.
Results are retained for 24 hours. After that, the result is deleted and the API returns status code 409.
If the stream is still running, the last 10 moderation results are returned per query.
If the stream has ended, all moderation results are returned.

QPS limits

QPS limit: 100 per user. If exceeded, the API call is throttled.

Debugging

Debug the VideoModerationResult API online in Alibaba Cloud OpenAPI to view sample code and SDK dependency information.

Request parameters

Name	Type	Required	Example	Description
Service	String	Yes	liveStreamDetection_global	The moderation service type. Must match the value used when submitting the job.
ServiceParameters	JSONString	Yes		A JSON string containing the query parameters. See the following table.

ServiceParameters

Name	Type	Required	Example	Description
taskId	String	Yes	abcd\\\\	The task ID of the job to query. Call `VideoModeration` to get the `TaskId` from the submit job response. Specify only one task ID per request.

Response parameters

Name	Type	Example	Description
Code	String	200	The status code. `280` means moderation is in progress; `200` means complete. See Status codes.
Message	String	OK	The response message.
RequestId	String	ABCD1234-1234-1234-1234-123\\\\	The request ID, used for troubleshooting.
Data	Object		The moderation result. See the following tables.

Data

Name	Type	Example	Description
DataId	String	videoId\\\\	The data ID specified in the moderation request. Returned only if `dataId` was specified.
LiveId	String	liveId\\\\	The live stream ID specified in the moderation request. Returned only if `liveId` was specified.
TaskId	String	AAAAA-BBBBB	The task ID of the moderation job.
RiskLevel	String	high	The overall risk level, determined from both video frames and audio. Valid values: `high`, `medium`, `low`, `none`. Act immediately on `high`-risk content, review `medium`-risk content manually, and treat `low`-risk content the same as `none` unless high recall is required. Configure risk score thresholds in the AI Guardrails console.
FrameResult	JSONObject		Video frame moderation results. See FrameResult below. Status code `280` means moderation is in progress; `200` means complete. Results reflect detections from the start of moderation to the current time while the stream is running.
AudioResult	JSONObject		Audio moderation results. See AudioResult below.

FrameResult

Name	Type	Example	Description
FrameNum	Integer	200	The number of snapshots returned.
RiskLevel	String	high	The risk level for video frames, calculated across all snapshots. Valid values: `high`, `medium`, `low`, `none`.
FrameSummarys	JSONArray		A summary of labels across all video frames. See FrameSummarys below.
Frames	JSONArray		Details of frames that matched a label. See Frames below.

FrameSummarys

Name	Type	Example	Description
Label	String	violent_armedForces	The detection label.
Description	String	Suspected to contain fireworks	A description of the label. This field is informational and may change. Base your handling logic on `Label`, not this field.
LabelSum	Integer	8	The number of times this label was detected.

Frames

Name	Type	Example	Description
TempUrl	String	http://www.aliyundoc.com/test.jpg	A temporary URL to the frame image, valid for 30 minutes. Save the frame promptly. 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 relative to the start of the live stream, in seconds.
Timestamp	Integer	1684559739000	The absolute timestamp when the frame was processed, in milliseconds.
RiskLevel	String	high	The risk level of this frame. Valid values: `high`, `medium`, `low`, `none`. Configure risk score thresholds in the AI Guardrails console.
Results	JSONArray		The moderation results for this frame, including labels and confidence scores. See Results below.

Results

Name	Type	Example	Description
Service	String	baselineCheck_global	The frame moderation service that produced this result.
Result	Array		The risk labels and confidence scores for this frame. See Result below.

Result

Name	Type	Example	Description
Label	String	violent_explosion	The detection label. For supported labels, see General baseline detection supported labels.
Confidence	Float	81.22	The confidence score, from 0 to 100, accurate to two decimal places.
Description	String	Suspected to contain fireworks	A description of the label. This field is informational and may change. Base your handling logic on `Label`, not this field.

AudioResult

Name	Type	Example	Description
RiskLevel	String	high	The risk level for audio, calculated across all audio segments. Valid values: `high`, `medium`, `low`, `none`.
AudioSummarys	JSONArray		A summary of labels across all audio. See AudioSummarys below.
SliceDetails	JSONArray		Details of each transcribed audio segment. See SliceDetails below.

AudioSummarys

Name	Type	Example	Description
Label	String	profanity	The detection label for audio.
LabelSum	Integer	8	The number of times this label was detected.

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 absolute start timestamp of the segment, in milliseconds.
EndTimestamp	Integer	1678854649720	The absolute end timestamp of the segment, in milliseconds.
Text	String	disgusting	The text transcribed from the audio segment.
Url	String	https://aliyundoc.com/test.wav	The temporary URL of the audio segment, valid for 30 minutes. Save the file promptly.
Labels	String	political_content,xxxx	Comma-separated detection labels. Valid values: `ad`, `violence`, `political_content`, `specified_speaking`, `specified_lyrics`, `sexual_content`, `sexual_sounds`, `contraband`, `profanity`, `religion`, `cyberbullying`, `negative_content`, `nontalk`, `C_customized`.
RiskLevel	String	high	The risk level of this audio segment. Valid values: `high`, `medium`, `low`, `none`.
RiskWords	String	AAA,BBB,CCC	Comma-separated risk words detected in the segment.
RiskTips	String	porn_vulgar_words,porn_description	Comma-separated sub-labels.
Extend	String	{"riskTips":"porn_vulgar_words","riskWords":"pornographic_service"}	A reserved field.

Examples

Request:

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

Response — video frames only:

{
    "Code": 200,
    "RequestId": "25106421-XXXX-XXXX-XXXX-15DA5AAAC546",
    "Message": "success finished",
    "Data": {
        "DataId": "dc16c28f-xxxx-xxxx-xxxx-51efe0131080",
        "LiveId": "live0307-0728-****",
        "RiskLevel": "high",
        "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 fireworks",
                    "LabelSum": 8
                },
                {
                    "Label": "sexual_cleavage",
                    "Description": "Suspected to contain nudity or sexual 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",
                    "Timestamp": 1704769999000
                },
                {
                    "Offset": 2,
                    "RiskLevel": "medium",
                    "Results": [
                        {
                            "Result": [
                                {
                                    "Confidence": 74.18,
                                    "Label": "violent_explosion",
                                    "Description": "Suspected to contain fireworks"
                                },
                                {
                                    "Confidence": 78.88,
                                    "Label": "sexual_cleavage",
                                    "Description": "Suspected to contain nudity or sexual content"
                                }
                            ],
                            "Service": "baselineCheck_global"
                        }
                    ],
                    "TempUrl": "http://abc.oss-ap-southeast-1.aliyuncs.com/test2.jpg",
                    "Timestamp": 1704769989000
                }
            ]
        }
    }
}

Response — video frames and audio:

{
    "Code": 200,
    "RequestId": "25106421-XXXX-XXXX-XXXX-15DA5AAAC546",
    "Message": "success finished",
    "Data": {
        "DataId": "dc16c28f-xxxx-xxxx-xxxx-51efe0131080",
        "LiveId": "live0307-0728-****",
        "RiskLevel": "high",
        "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 fireworks",
                    "LabelSum": 8
                },
                {
                    "Label": "sexual_cleavage",
                    "Description": "Suspected to contain nudity or sexual 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",
                    "Timestamp": 1704769999000
                },
                {
                    "Offset": 2,
                    "RiskLevel": "medium",
                    "Results": [
                        {
                            "Result": [
                                {
                                    "Confidence": 74.18,
                                    "Label": "violent_explosion",
                                    "Description": "Suspected to contain fireworks"
                                },
                                {
                                    "Confidence": 78.88,
                                    "Label": "sexual_cleavage",
                                    "Description": "Suspected to contain nudity or sexual content"
                                }
                            ],
                            "Service": "baselineCheck_global"
                        }
                    ],
                    "TempUrl": "http://abc.oss-ap-southeast-1.aliyuncs.com/test2.jpg",
                    "Timestamp": 1704769989000
                }
            ]
        }
    }
}

Cancel a moderation job

Operation: VideoModerationCancel

Cancels a running live stream moderation job. This operation is free of charge.

Debugging

Debug the VideoModerationCancel API online in Alibaba Cloud OpenAPI to view sample code and SDK dependency information.

Request parameters

Name	Type	Required	Example	Description
Service	String	Yes	liveStreamDetection_global	The moderation service type. Must match the value used when submitting the job.
ServiceParameters	JSONString	Yes		A JSON string containing the cancellation parameters. See the following table.

ServiceParameters

Name	Type	Required	Example	Description
taskId	String	Yes	abcd\\\\	The task ID of the job to cancel. Call `VideoModeration` to get the `TaskId` from the submit job response. Specify only one task ID per request.

Response parameters

Name	Type	Example	Description
Code	Integer	200	The status code. See Status codes.
Message	String	OK	The response message.
RequestId	String	AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE\\\\	The request ID.

Example

Request:

Response:

{
    "Msg": "OK",
    "Code": 200,
    "RequestId": "70ED13B0-BC22-576D-9CCF-1CC12FEAC477"
}

Status codes

Requests returning status code 200 or 280 are billed. All other status codes are not billed.

Code	Description
200	Request successful or moderation complete.
280	Moderation in progress.
400	Request parameters are empty.
401	Request parameters are invalid.
402	A parameter value exceeds the allowed length. Check the parameter and try again.
403	QPS limit exceeded. Reduce the number of concurrent requests and try again.
404	Failed to download the video. Check the stream URL and try again.
405	Video download timed out. The stream may be inaccessible. Check the stream URL and try again.
406	Video file is too large. Check the video size and try again.
407	Video format not supported. Check the format and try again.
408	Not authorized. Your account may not have the service activated, may have an overdue payment, or may not have the required permissions.
409	The specified task ID does not exist. The result may have expired after 24 hours.
480	Concurrent stream limit exceeded. Reduce the number of concurrent jobs and try again.
500	System error.