Asynchronous detection for video moderation - AI Guardrails

Video moderation helps you detect risky or non-compliant content in videos, with support for pornography detection, terrorist content detection, ad violation detection, undesirable scene detection, logo detection, and audio anti-spam. This topic explains how to use an API to asynchronously detect content in videos.

Asynchronous video moderation

Use the /green/video/asyncscan API to perform asynchronous video moderation.

You can call this operation to create asynchronous video moderation tasks. See Request syntax to learn how to construct an HTTP request, or use a pre-built request from the SDK overview.

Billing
This is a paid API operation. For more information about billing, see Content Moderation Pricing.
If you moderate content across multiple scenarios, you are charged the cumulative fee for all scenarios. The fee for each scenario is the number of moderated video frames multiplied by the scenario's unit price. Using the audio anti-spam feature incurs an additional fee. This fee is the video duration multiplied by the unit price of the audio anti-spam feature.
Moderated object
You can call this operation to moderate a video file or a video stream. You can specify the video file by submitting a sequence of captured frames or by providing a video URL.
Return Results
Asynchronous detection tasks do not return results in real time. You must use a callback or polling to retrieve the results, which are stored for up to one hour.
- Obtain results by using a callback: When you submit an asynchronous moderation task, include the callback parameter in the request to automatically receive the moderation results. For more information, see Request parameters.
- Use polling: Submit the asynchronous moderation task without the callback parameter. Then, call the result query operation to obtain the moderation results. For more information, see Description of the /green/video/results operation.

Video requirements

The video file URL must use the HTTP or HTTPS protocol.
Supported video file formats: AVI, FLV, MP4, MPG, ASF, WMV, MOV, WMA, RMVB, RM, FLASH, and TS.
Video size limit: The default maximum size of a single video file is 200 MB.

If you need to process videos larger than 200 MB, you must split them into smaller segments. Alternatively, join the DingTalk group (ID: 35573806) to contact technical support and request a limit increase.
Supported video stream protocols: RTMP, HLS, HTTP-FLV, and RTSP.
Video stream duration limit: A single video stream detection task runs for a maximum of 24 hours. The task automatically ends if it exceeds this limit.
The video detection time depends on the video download time. Ensure that the storage service where the video file is stored is stable and reliable. We recommend that you use Alibaba Cloud OSS to store your video files.

Table 1.Use case description

Use case	Description	Detection Result Classification
Video pornography detection	Detects whether the video contains pornographic content.	Normal, Pornography
Video violence, terrorism, and politically sensitive content detection	Detects whether the video contains violent, terrorist, or politically sensitive content.	Normal, Violence/Terrorism/Politically Sensitive
Video inappropriate scene detection	Detects whether the video contains inappropriate scenes.	Normal, Inappropriate Scene (such as black screen, white screen)
Video logo	Detects whether the video contains a specific logo.	Normal, Logo
Video text and image violation detection	Detects whether the video contains advertisements or prohibited text content.	Normal, Advertisement or Text Violation
Video audio violation detection Note This scenario is supported only through the asynchronous video detection API. For more information, see Asynchronous detection.	Detects whether the audio in the video contains prohibited information. Note The default recognition language is Chinese. To recognize English content, contact your account manager.	Normal, Spam, Advertisement, Politically Sensitive, Violence/Terrorism, Insulting Language, Pornography, Flooding, Prohibited Content, Custom (such as hitting custom keywords)

QPS limit

The queries per second (QPS) limit for this API is 50 per user, with a concurrency limit of 20 streams. This means a maximum of 20 tasks can be processed at the same time. To increase the concurrency limit, contact your business manager. Exceeding these limits triggers throttling, which can impact your business. Plan your calls accordingly.

Note

If real-time processing is not a high priority, we recommend that you enable offline detection mode. In this mode, the detection task starts within 24 hours after submission.

Request parameters

Parameter	Type	Required	Example	Description
bizType	String	No	default	This field identifies your business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize moderation rules.
live	Boolean	No	false	Specifies whether to moderate a live stream. Valid values: false (default): video-on-demand moderation. true: live stream moderation.
offline	Boolean	No	false	Enables the offline moderation mode. Valid values: false (default): The real-time moderation mode is used. In this mode, the service rejects moderation requests that exceed the task concurrency limit. true: Enables the offline moderation mode. In this mode, submitted tasks are queued and not guaranteed to be processed in real time. The moderation starts within 24 hours. Note This parameter applies only to video-on-demand moderation. It is not required for live stream moderation.
scenes	StringArray	Yes	["porn"]	Specifies the video moderation scenarios. Valid values: porn: pornography detection terrorism: terrorist content detection live: undesirable scene detection Logo: logo detection ad: ad violation detection
audioScenes	StringArray	No	["antispam"]	The audio moderation scenario. The only valid value is antispam for audio anti-spam. If you omit this parameter, the service moderates only the video content. If specified, the service also moderates the audio track. Note To moderate the audio in a video, you must provide the video URL by using the url parameter in the task object. Audio moderation is not supported when you submit video content as a sequence of frame captures by using the frames parameter in the task object.
callback	String	No	http://www.aliyundoc.com	The URL to which you want to receive callback notifications for the detection results. The URL must use the HTTP or HTTPS protocol. If you leave this parameter empty, you must periodically poll for the detection results. The `callback` interface must support the POST method, UTF-8 encoded data, and the form parameters checksum and content. Content Moderation sets the checksum and content parameters according to the following rules and formats, and calls your `callback` interface to return the detection results. checksum: A SHA-256 hash of the concatenated string `User UID + seed + content`. The user UID is your Alibaba Cloud account ID, which is available in the Alibaba Cloud console. To prevent tampering, regenerate this string on your end and verify it against the received checksum. Note The user UID must be that of the root account, not a RAM user. content: A JSON string that you must parse. For an example of the content payload, see the sample response in "Query detection results". Note After your callback server receives a result notification, it must return an HTTP status code of 200 to indicate success. Any other status code is treated as a failure. If the notification fails, Content Moderation retries up to 16 times until it succeeds. If it still fails after 16 retries, no more attempts are made. We recommend that you check the status of your callback endpoint.
seed	String	No	abc****	A random string used for the signature in the callback notification request. The string can contain letters, digits, and underscores (_), and must be 64 characters or less. Customize this string to verify the origin of callback requests. Note This parameter is required when you use a callback.
cryptType	String	No	SHA256	If you use callback notifications, this parameter specifies the hashing algorithm for the callback signature (checksum). Content Moderation generates the checksum by hashing the string (concatenated from `Alibaba Cloud account ID + seed + content`) with the specified algorithm before sending it to your callback URL. Valid values: SHA256 (Default): Uses the SHA-256 hashing algorithm. SM3: Uses the SM3 hashing algorithm. A hexadecimal string that consists of lowercase letters and digits is returned. For example, hashing abc with SM3 returns 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0.
tasks	JSONArray	Yes		A JSON array of task objects, each specifying a moderation object. You can submit up to 100 tasks in a single request, provided that the task concurrency is 100 or higher. For more information about the structure of a task object, see task.

Table 1. task

Parameter	Type	Required	Example	Description
clientInfo	JSONObject	No	{"userId":"12023****","userNick":"Mike","userType":"others"}	The client information. For more information, see the common query parameters in Common parameters. The server merges the global clientInfo with the individual clientInfo specified for the request. Note The individual clientInfo has a higher priority.
dataId	String	No	videoId****	The data ID of the detection object. This ID can contain uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.), and must be 128 characters or less. Use it to uniquely identify your business data.
liveId	String	No	liveId****	The ID of the live video stream. This parameter is used to prevent duplicate detection tasks for video live streams. If you pass this parameter, the system checks whether a detection task is already in progress based on `uid+bizType+liveId`. If a task is in progress, the system returns the taskId of the existing task instead of creating a new one.
url	String	No	http://www.aliyundoc.com/a.flv	A public HTTP or HTTPS URL. The URL cannot exceed 2,048 characters in length. Note Specify either frames or url. If you specify the url parameter, you are charged based on the billing method for submitting video URLs.
frames	JSONArray	No		The frame information for the video to be detected. Each element in frames is a struct. For a detailed description of the structure of each element, see frame. Note Specify either frames or url. If you pass the url parameter, you are billed for submitting a video URL.
framePrefix	String	No	http://www.aliyundoc.com/video/	The prefix of the frame URL. This prefix is combined with `frame.url` to form the complete URL of a video frame. The format of the complete URL is `framePrefix + frame.url`.
interval	Integer	No	1	The interval for video frame capture. Unit: seconds. Valid values: 1 to 600. The default value is 1.
maxFrames	Integer	No	200	The maximum number of frames to capture from the video. Valid values: 5 to 3,600. The default value is 200. To request a higher limit, contact us through Support and Services. Note This field applies only to video file detection (live=false). For video stream detection (live=true), this parameter is ignored, and there is no upper limit on the number of captured frames. When you use an OSS address (which starts with `oss://`) as the video source address and authorize the Content Moderation service to access ApsaraVideo Media Processing (MPS), you can capture a maximum of 20,000 images. This method does not incur additional fees. For more information about how to authorize the Content Moderation service to access MPS, see Authorize access to the MPS service.

Table 2. frame

Parameter	Type	Required	Example	Description
url	String	No	http://www.aliyundoc.com/0B860000586C0A0300038A0460000	The URL of the video frame is combined with `framePrefix` to form the full URL of the frame. The format of the full URL is `framePrefix + frame.url`.
offset	Integer	No	10	The frame's time offset from the start of the video, in seconds.

Response parameters

Parameter	Type	Example	Description
taskId	String	taskId****	The ID of the moderation task.
dataId	String	videoId****	The data ID of the detection object. Note If dataId was passed in the detection request, the same dataId is returned here.

Examples

Sample requests

Submit video frames

http(s)://[Endpoint]/green/video/asyncscan
&<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"
                }
            ]
        }
    ]
}

Submit a video file

http(s)://[Endpoint]/green/video/asyncscan
&<common request parameters>
{
    "scenes": [
        "porn"
    ],
    "audioScenes": [
        "antispam"
    ],
    "tasks": [
        {
            "dataId": "videoId****",
            "url": "http://www.aliyundoc.com/a.mp4",
            "interval": 1,
            "maxFrames": 200
        }
    ]
}

Submit a live stream

http(s)://[Endpoint]/green/video/asyncscan
&<common request parameters>
{
    "scenes": [
        "porn"
    ],
    "live": true,
    "tasks": [
        {
            "dataId": "videoId****",
            "url": "http://www.aliyundoc.com/a.flv",
            "interval": 1,
            "maxFrames": 200
        }
    ]
}

Success response

{
    "code": 200,
    "msg": "OK",
    "requestId": "requestID****",
    "data": [
        {
            "dataId": "videoId****",
            "taskId": "taskId****"
        }
    ]
}

Query asynchronous moderation results

API: /green/video/results

Use this operation to query the results of an asynchronous moderation task. To construct an HTTP request, see request syntax. You can also use a pre-built request with an SDK, as described in the SDK overview.

Billing
This API operation is free of charge.
Result availability
Set the polling interval to 30 seconds, which means you query the result 30 seconds after you submit an asynchronous detection task. The result is stored for up to one hour and is discarded if not retrieved within that time.

QPS limit

The queries per second (QPS) limit for this API is 50 per user. Exceeding this limit triggers throttling, which can impact your business. Plan your calls accordingly.

Request parameters

Parameter	Type	Required	Example	Description
body	JSONArray	Yes	["taskId**","taskId**"]	A list of taskId values for the detection tasks you want to query. The array can contain up to 100 elements. You can obtain the taskId from the response after you submit a detection task.

Response parameters

Parameter	Type	Example	Description
code	Integer	200	The error code. It is the same as the HTTP status code. For more information, see Common error codes.
msg	String	OK	The response message.
dataId	String	videoId****	The data ID of the detection object. Note If dataId was passed in the detection request, the same dataId is returned here.
taskId	String	taskId****	The ID of the moderation task.
results	JSONArray		An array of result objects, one for each requested moderation scenario. This parameter is returned only on successful requests where `code` is 200. For details about the object structure, see result. Note In live stream moderation scenarios, a `code` of 280 indicates that the moderation is in progress, and 200 indicates that the moderation is complete. When the moderation is in progress, the results include all findings up to the current time.
audioScanResults	JSONArray		The results of audio moderation. For details about the structure, see audioScanResult.

Table 3. result

Parameter	Type	Example	Description
scene	String	porn	The moderation scenario specified in the request. Valid values: porn: pornography detection terrorism: terrorist content detection live: undesirable scene detection Logo: logo detection ad: ad violation detection
label	String	porn	The moderation result label. Valid values vary based on the moderation scenario: For porn (pornographic content detection): normal: normal content porn: pornographic content For terrorism (terrorist content detection): normal: normal content terrorism: terrorist content For live (undesirable scene detection): normal: normal content live: undesirable scene For Logo (logo detection): normal: normal content Logo: logo detected For ad (ad and text violation detection): normal: normal content ad: ad or text violation
sublabel	String	porn	If the detection scenes include pornography (porn) and terrorism/politics (terrorism), this field can return fine-grained labels for the detection results. This field is not returned by default.
suggestion	String	block	The recommended action. Valid values: pass: The content is compliant and requires no further action. review: The content might be non-compliant, and a manual review is recommended. block: The content is non-compliant. We recommend that you block the content or restrict its visibility.
rate	Float	99.2	The confidence score. Valid values: 0 (lowest confidence) to 100 (highest confidence). If the suggestion is pass, the higher the confidence score, the more likely the content is compliant. If the suggestion is review or block, the higher the confidence score, the more likely the content is non-compliant. Important We recommend that you use the suggestion and label (or sublabel, for some API operations) fields to determine whether the content is in violation.
frames	JSONArray		An array of video frames that contain non-compliant content. For details about the structure, see frame.
hintWordsInfo	JSONArray		If the video contains ad or text violations, this parameter returns information about the risk keywords found in the text. For details about the structure, see hintWordsInfo. Note This parameter is available only for the ad and text violation detection (ad) scenario.
logoData	JSONArray		If the video contains a logo, this parameter returns information about the detected logo. For details about the structure, see logoData. Note This parameter is available only for the logo detection (logo) scenario.
sfaceData	JSONArray		If the video contains terrorist or political content, this parameter returns information about detected faces. For details about the structure, see sfaceData. Note This parameter is available only for the terrorist content detection (terrorism) scenario.

Table 4. frame

Parameter	Type	Example	Description
url	String	http://www.aliyundoc.com/0B860000586C0A0	The URL of the video frame.
offset	Integer	50	The time offset of the video frame from the start of the video, in seconds.
label	String	porn	The moderation result label for the video frame. Valid values vary based on the moderation scenario: For `porn` (pornographic content detection): normal: normal content sexy: suggestive content porn: pornographic content For `terrorism` (terrorist content detection): normal: normal content bloody: bloody content explosion: explosions and smoke outfit: special costumes Logo: special logos weapon: weapons politics: political content violence: violent acts crowd: crowds parade: parades carcrash: car crashes flag: flags location: specific locations drug: drug-related content gamble: gambling-related content others: other content For `ad` (ad and text violation detection): normal: normal content politics: political text porn: pornographic text abuse: abusive text terrorism: terrorist text contraband: text about contraband spam: spam text npx: overlay ads qrcode: QR codes programCode: mini program codes ad: other ads For `live` (undesirable scene detection): normal: normal content meaningless: meaningless scenes (such as a black or white screen) PIP: Picture-in-Picture (PiP) streaming smoking: smoking drivelive: live streaming from a moving vehicle drug: drug-related content gamble: gambling-related content For `logo` (logo detection): normal: normal content TV: controlled media logos trademark: trademarks
rate	Float	99.1	The confidence score. Valid values: 0 to 100. A higher confidence score indicates a higher probability that the detection result is accurate. Avoid using this score in your business logic.

Table 5. audioScanResult

Parameter	Type	Example	Description
scene	String	antispam	The audio moderation scenario. The only valid value is antispam, which indicates audio anti-spam.
label	String	customized	The category of the audio moderation result. Valid values: normal: normal audio spam: spam ad: ads politics: political content terrorism: terrorist content abuse: abusive language porn: pornographic content flood: excessive spam contraband: contraband customized: a match found in a custom text library
suggestion	String	block	The recommended action. Valid values: pass: The content is compliant and requires no further action. review: The content might be non-compliant, and a manual review is recommended. block: The content is non-compliant. We recommend that you block the content or restrict its visibility.
rate	Float	99.91	The confidence score. Valid values: 0 (lowest confidence) to 100 (highest confidence). If the suggestion is pass, the higher the confidence score, the more likely the content is compliant. If the suggestion is review or block, the higher the confidence score, the more likely the content is non-compliant. Important We recommend that you use the suggestion and label (or sublabel, for some API operations) fields to determine whether the content is in violation.
details	JSONArray		The audio transcript details. This array contains one or more sentence objects. For details about the structure, see detail.

Table 6. detail

Parameter	Type	Example	Description
startTime	Integer	24	The start time of the sentence, in seconds.
endTime	Integer	60	The end time of the sentence, in seconds.
text	String	computer	The transcribed text of the audio.
label	String	normal	The category of the moderation result for the sentence. Valid values: normal: normal audio spam: spam ad: ads politics: political content terrorism: terrorist content abuse: abusive language porn: pornographic content flood: excessive spam contraband: contraband customized: a match found in a custom text library
keyword	String	enable	The matched custom keyword, if any.
libName	String	manual	If a custom keyword is matched, this parameter returns the name of the text library that contains the keyword.

Table 7. logoData

Parameter	Type	Example	Description
type	String	TV	The type of the detected logo. The value `TV` indicates a controlled media logo.
name	String	***TV	The name of the detected logo.
x	Float	140	The x-coordinate of the upper-left corner of the logo's bounding box. The origin is the top-left corner of the image. Unit: pixels.
y	Float	68	The y-coordinate of the upper-left corner of the logo's bounding box. The origin is the top-left corner of the image. Unit: pixels.
w	Float	106	The width of the logo's bounding box. Unit: pixels.
h	Float	106	The height of the logo's bounding box. Unit: pixels.

Table 5. sfaceData

Parameter	Type	Example	Description
x	Float	444	The x-coordinate of the face bounding box, relative to the image's top-left corner.
y	Float	174	The y-coordinate of the face bounding box, relative to the image's top-left corner.
w	Float	467	The width of the face bounding box.
h	Float	467	The height of the face bounding box.
smileRate	Float	0	The probability of a smile.
glasses	Boolean	false	Indicates whether the person is wearing glasses.
faces	Array		An array of recognized face objects. For the structure of each object, see Table 6.

Table 8. face

Parameter	Type	Example	Description
name	String	xxxx	The name of the similar person.
rate	Float	97.03	The similarity probability.
id	String	AliFace_001****	The face ID.

Table 8. hitLibInfo

Parameter	Type	Example	Description
context	String	xxxx	The matched content from a custom text library.
libCode	String	69751	The code of the custom text library.
libName	String	manual	The name of the custom text library.

Table 9. hintWordsInfo

Parameter	Type	Example	Description
context	String	xxxx	The matched risk keyword.

Examples

Sample request

http(s)://[Endpoint]/green/video/results
&<common request parameters>
[
    "taskId****",
    "taskId****"
]

Sample responses

Moderating images only

{
    "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"
                }
            ]
        }
    ]
}

Moderating both images and audio

{
    "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"
                }
            ],
            "audioScanResults": [
                {
                    "scene": "antispam",
                    "label": "customized",
                    "suggestion": "block",
                    "rate": 99.91,
                    "details": [
                        {
                            "startTime": 0,
                            "endTime": 24,
                            "text": "computer",
                            "label": "customized"
                        },
                        {
                            "startTime": 24,
                            "endTime": 60,
                            "text": "computer",
                            "label": "normal"
                        }
                    ]
                }
            ]
        }
    ]
}