Asynchronous video moderation - Content Moderation - Alibaba Cloud Documentation Center

You can call the /green/video/asyncscan operation to moderate videos for risky or illegal content and call the /green/video/results operation to query moderation results. These operations are applicable to the following scenarios: pornography detection, terrorist content detection, ad violation detection, undesirable scene detection, logo detection, and audio anti-spam. This topic describes the operations that you can call to asynchronously moderate videos.

Description of the /green/video/asyncscan operation

Operation: /green/video/asyncscan

You can call this operation to submit asynchronous video moderation tasks. For more information about how to construct an HTTP request, see Request syntax. You can also select an existing HTTP request. For more information, see SDK overview.

Billing
You are charged for calling this operation. For more information about the billing methods, see Content Moderation Pricing.
If your moderation occurs in multiple scenarios at a time, you are charged the cumulative fee of all scenarios. The fee for each scenario equals the number of video frames that are moderated in the scenario multiplied by the unit price in the scenario. If you moderate the audio in a video at the same time, you are charged an extra fee for audio anti-spam. The extra fee equals the video duration multiplied by the unit price of audio anti-spam.
Moderated object
You can call this operation to moderate videos or video streams. You can submit a sequence of frames that are captured from a video or submit a video URL to specify the video to be moderated.
Return results
If you send asynchronous moderation requests, the moderation results are not returned in real time. To obtain moderation results, you can poll the moderation results periodically or enable callback notification. The moderation results are retained for up to 1 hour.
- Enable callback notification to obtain moderation results: When you submit asynchronous moderation tasks, you can specify a callback URL for receiving moderation results in the callback parameter of the moderation request. For more information about the callback parameter, see Request parameters.
- Poll moderation results at regular intervals: You do not need to set the callback parameter when you submit asynchronous moderation tasks. After you submit the tasks, you can call the /green/video/results operation to query moderation results. For more information about the operation, see Description of the /green/video/results operation.
Limits on videos
- The URLs of videos must be HTTP or HTTPS URLs.
- The videos must be in AVI, FLV, MP4, MPG, ASF, WMV, MOV, WMA, RMVB, RM, FLASH, or TS format.
- A video can be up to 200 MB in size.
  If the video to be moderated exceeds 200 MB, the video must be segmented. You can join the DingTalk Group (DingTalk Group number: 35573806) and contact the technical support personnel to help you adjust the size limit.
- Video streams must be transferred by using the RTMP, HLS, HTTP-FLV, or RTSP protocol.
- The duration of a video stream moderation task can be up to 24 hours. If the duration exceeds 24 hours, the moderation task automatically ends.
- The duration of a video moderation task varies based on the duration for downloading the video. Make sure that you use a stable and reliable storage service to store the videos to be moderated. We recommend that you use Object Storage Service (OSS).

Table 1. Scenarios
Scenario	Description	Category of the moderation result
Pornography detection	Detects pornographic content in a video.	normal and porn
Terrorist content detection	Detects terrorist content in a video.	normal and terrorism
Undesirable scene detection	Detects undesirable scenes in a video.	normal and live
Logo detection	Detects specific logos in a video.	normal and logo
Ad violation detection	Detects ads or text violations in a video.	normal and ad
Audio anti-spam Note For this scenario, you must call the /green/video/asyncscan operation to submit asynchronous video moderation tasks. For more information, see /green/video/asyncscan and /green/video/results.	Detects audio anti-spam in a video. Note By default, the audio to be moderated must be in Chinese. If you need to moderate audio in English, contact your sales manager.	normal, spam, ad, politics, terrorism, abuse, porn, flood, contraband, and customized

QPS limit

You can call this operation up to 50 times per second per account. Only 20 moderation tasks can be processed at a time. If you need to increase the number of concurrent moderation tasks, consult your business manager. If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation.

Note

If you do not need to moderate data in real time, we recommend that you enable offline moderation. In offline moderation mode, the system starts moderating within 24 hours after you submit a task.

Request parameters

Parameter	Type	Required	Example	Description
bizType	String	No	default	The business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize policies for machine-assisted moderation.
live	Boolean	No	false	Specifies whether to moderate live streams. Valid values: false: moderates videos. This is the default value. true: moderates live streams.
offline	Boolean	No	false	Specifies whether to enable the offline moderation mode. Valid values: false: enables the real-time moderation mode. In this mode, Content Moderation rejects moderation requests beyond the task concurrency limit. This is the default value. true: enables the offline moderation mode. In this mode, the moderation tasks you submit may not be processed in real time, but can be queued for processing and will start within 24 hours. Note This parameter is applicable only to video moderation. This parameter is not required for video stream moderation.
scenes	StringArray	Yes	["porn"]	The video moderation scenario. 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. Set the value to antispam. If you do not set this parameter, Content Moderation moderates only images in videos. If you set this parameter, Content Moderation also moderates audio in videos. Note To moderate the audio in a video, you must set the url parameter in the task parameter to submit the URL of the video or video stream. Audio moderation is inapplicable if you set the frames parameter in the task parameter to submit a sequence of frames that are captured from a video.
callback	String	No	http://www.aliyundoc.com	The callback URL for notifying you of asynchronous moderation results. HTTP and HTTPS URLs are supported. If you do not set this parameter, you must poll moderation results periodically. If you set the callback parameter in the moderation request, make sure that the specified HTTP or HTTPS URL meets the following requirements: supports the POST method, uses UTF-8 to encode the transmitted data, and supports the checksum and content parameters. To send moderation results to the specified callback URL, Content Moderation returns the checksum and content parameters in callback notifications based on the following rules and format: checksum: the string in the UID + Seed + Content format that is generated by the Secure Hash Algorithm 256 (SHA-256) algorithm. UID indicates the ID of your Alibaba Cloud account. You can query the ID in the Alibaba Cloud Management Console. To prevent data tampering, you can use the SHA-256 algorithm to generate a string when your server receives a callback notification and verify the string against the received checksum parameter. Note UID must be the ID of an Alibaba Cloud account, but not the ID of a RAM user. content: the JSON-formatted string to be parsed to the callback data in the JSON format. For more information about the format of the content parameter, see the sample success responses of each operation that you can call to query asynchronous moderation results. Note If your server receives a callback notification, the server sends an HTTP 200 status code to Content Moderation. If your server fails to receive a callback notification, the server sends other HTTP status codes to Content Moderation. If your server fails to receive a callback notification, Content Moderation continues to push the callback notification until your server receives it. Content Moderation can push a callback notification repeatedly up to 16 times. After 16 times, Content Moderation stops pushing the callback notification. In this case, we recommend that you check the status of the callback URL.
seed	String	No	abc****	A random string that is used to generate a signature for the callback notification request. The string can be up to 64 characters in length and can contain letters, digits, and underscores (_). You can customize this string. It is used to verify the callback notification request when Content Moderation pushes callback notifications to your server. Note This parameter is required if you set the callback parameter.
cryptType	String	No	SHA256	The encryption algorithm used to encrypt the callback notification content when you enable callback notification. Content Moderation encrypts the returned string by using the encryption algorithm that you specify and sends the encrypted string to the callback URL. The returned string is in the `UID + Seed + Content` format. Valid values: SHA256: The HMAC-SHA256 encryption algorithm is used. This is the default value. SM3: The HMAC-SM3 encryption algorithm is used, and a hexadecimal string is returned. The string consists of lowercase letters and digits. For example, 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 is returned after you encrypt abc by using the HMAC-SM3 encryption algorithm.
tasks	JSONArray	Yes		The list of objects that you want to moderate. The JSON array can contain one or more elements. Each element is a structure. The JSON array can contain up to 100 elements. In other words, you can submit up to 100 text entries at a time. To submit 100 text entries at a time, you must raise the relevant concurrency limit to a number greater than 100. For more information about the structure, see task.

Table 1. task
Parameter	Type	Required	Example	Description
clientInfo	JSONObject	No	{"userId":"12023****","userNick":"Mike","userType":"others"}	The information about the client. For more information, see the "Common request parameters" section of Common parameters. The server determines whether to use the global clientInfo parameter or the clientInfo parameter that is described in this table. Note The clientInfo parameter in this table takes priority over the global one.
dataId	String	No	videoId****	The ID of the moderation object. The ID can contain letters, digits, underscores (_), hyphens (-), and periods (.). It can be up to 128 characters in length. This ID uniquely identifies your business data.
liveId	String	No	liveId****	The ID of the video live stream. This parameter is used to prevent repeated moderation of video live streams. If you specify this parameter, Content Moderation checks whether a task for moderating the specified video live stream is in progress based on the ID of the Alibaba Cloud account and the bizType and liveId parameters. If the moderation task is in progress, the taskId of the task is returned, and no new task is initiated.
url	String	No	http://www.aliyundoc.com/a.flv	The HTTP or HTTPS URL that can be accessed over the Internet. The URL is up to 2,048 characters in length. Note You must set one of the frames and url parameters. If you set the url parameter, you are charged for the video moderation task based on the unit price for moderating videos submitted by specifying their URLs.
frames	JSONArray	No		The information about frames that are captured from the video to be moderated. Each element in the JSON array of the frames parameter is a structure. For more information about the structure of each element, see frame. Note You must set one of the frames and url parameters. If you set the url parameter, you are charged for the video moderation task based on the unit price for moderating videos submitted by specifying their URLs.
framePrefix	String	No	http://www.aliyundoc.com/video/	The prefix of the URL of a captured frame, which is used with `frame.url` to form the complete URL of the captured frame. The complete URL of a captured frame is in the format of `framePrefix + frame.url`.
interval	Integer	No	1	The interval for capturing frames from the video. Unit: seconds. Valid values: 1 to 600. Default value: 1.
maxFrames	Integer	No	200	The maximum number of frames that can be captured from the video. Valid values: 5 to 3600. Default value: 200. If you need to set this parameter to a greater value, submit a ticket on Support and Services. Note This parameter is valid only when you set the live parameter to false to moderate videos. If you set the live parameter to true to moderate live streams, the number of frames that can be captured from live streams is not limited. If you use an Object Storage Service (OSS) URL that starts with `oss://` as the source URL of a video and authorize Content Moderation to access ApsaraVideo Media Processing (MPS), you can capture a maximum of 20,000 frames from the video. You are not charged extra fees when you use this method. For more information about how to authorize Content Moderation to access MPS, see Authorize a role to access ApsaraVideo for Media Processing.

Table 2. frame
Parameter	Type	Required	Example	Description
url	String	No	http://www.aliyundoc.com/0B860000586C0A0300038A0460000	The URL of the captured frame, which is used with `framePrefix` to form the complete URL of the captured frame. The complete URL of a captured frame is in the format of `framePrefix + frame.url`.
offset	Integer	No	10	The interval between the start of the video and the captured frame. Unit: seconds.

Response parameters

Parameter	Type	Example	Description
taskId	String	taskId****	The ID of the moderation task.
dataId	String	videoId****	The ID of the moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here.

Examples

Sample requests

Moderate frames that are captured from a video

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

Moderate a video

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

Moderate 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
        }
    ]
}

Sample success responses

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

Description of the /green/video/results operation

Operation: /green/video/results

You can call this operation to query asynchronous video moderation results. For more information about how to construct an HTTP request, see Request syntax. You can also select an existing HTTP request. For more information, see SDK overview.

Billing
This operation is free of charge.
Response timeout
We recommend that you query moderation results at least 30 seconds after you send an asynchronous moderation request. Content Moderation retains moderation results for up to 4 hours. After 4 hours, the results are deleted.

QPS limit

You can call this operation up to 50 times per second per account. If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation.

Request parameters

Parameter	Type	Required	Example	Description
body	JSONArray	Yes	["taskId**","taskId**"]	The list of IDs of asynchronous moderation tasks that you want to query. The array can contain up to 100 elements. After you submit a moderation task, you can obtain the ID of the task from the response.

Response parameters

Parameter	Type	Example	Description
code	Integer	200	The returned HTTP status code. For more information, see Common error codes.
msg	String	OK	The message that is returned in response to the request.
dataId	String	videoId****	The ID of the moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here.
taskId	String	taskId****	The ID of the moderation task.
results	JSONArray		If the call is successful, the HTTP status code 200 and moderation results are returned. The moderation results contain one or more elements. Each element is a structure. For more information about the structure, see result. Note In the scenario of moderating a video stream, the HTTP status code 280 indicates that the moderation task is in progress, and the HTTP status code 200 indicates that the moderation task is complete. If the moderation task is in progress, the returned moderation results contain all the issues that Content Moderation has detected in the task.
audioScanResults	JSONArray		The audio moderation results. For more information about the structure, see audioScanResult.

Table 3. result
Parameter	Type	Example	Description
scene	String	porn	The video moderation scenario that you specified in the moderation 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 category of the video moderation result. Valid values: If the scenes parameter is set to porn, the valid values are: normal: normal porn: pornographic content If the scenes parameter is set to terrorism, the valid values are: normal: normal terrorism: terrorist content If the scenes parameter is set to live, the valid values are: normal: normal live: undesirable scene If the scenes parameter is set to logo, the valid values are: normal: normal logo: logo If the scenes parameter is set to ad, the valid values are: normal: normal ad: ad or text violation
sublabel	String	porn	If the scenes parameter is set to porn or terrorism, the subcategory of the moderation result can be returned in this parameter. This parameter is not returned by default.
suggestion	String	block	The recommended subsequent operation. Valid values: pass: The moderation object does not require further actions. review: The moderation object contains suspected violations and requires manual review. block: The moderation object contains violations. We recommend that you delete or block the object.
rate	Float	99.2	The score of the confidence level. Valid values: 0 to 100. A greater value indicates a higher confidence level. If a value of pass is returned for the suggestion parameter, a higher confidence level indicates a higher probability that the content is normal. If a value of review or block is returned for the suggestion parameter, a higher confidence level indicates a higher probability that the content contains violations. Important We recommend that you use the values that are returned for the suggestion, label, and sublabel parameters to determine whether the content contains violations. The sublabel parameter is returned by specific operations.
frames	JSONArray		The information about the captured frames that contain violations. For more information about the structure, see frame.
hintWordsInfo	JSONArray		The information about the term hit by the ad or illegal text detected in the moderated video. For more information about the structure, see hintWordsInfo. Note This parameter is applicable only to ad violation detection.
logoData	JSONArray		The information about the logo detected in the moderated video. For more information about the structure, see logoData. Note This parameter is applicable only to logo detection.
sfaceData	JSONArray		The information about the terrorist content detected in the moderated video. For more information about the structure, see sfaceData. Note This parameter is applicable only to terrorist content detection.

Table 4. frame
Parameter	Type	Example	Description
url	String	http://www.aliyundoc.com/0B860000586C0A0	The URL of the captured frame.
offset	Integer	50	The interval between the start of the video and the captured frame. Unit: seconds.
label	String	porn	The category of the moderation result of the captured frame. Valid values: If the scenes parameter is set to porn, the valid values are: normal: normal sexy: suggestive content porn: pornographic content If the scenes parameter is set to terrorism, the valid values are: normal: normal bloody: bloody content explosion: explosion and smoke outfit: special costume logo: logo weapon: weapon politics: political content violence: violence crowd: crowd parade: parade carcrash: car crash flag: flag location: landmark drug: drugs gamble: gambling others: other content If the scenes parameter is set to ad, the valid values are: normal: normal politics: political content in text porn: pornographic content in text abuse: abuse in text terrorism: terrorist content in text contraband: prohibited content in text spam: junk content in text npx: overlay ad qrcode: QR code programCode: mini program code ad: other ads If the scenes parameter is set to live, the valid values are: normal: normal meaningless: no content, such as black or white screen PIP: Picture-in-Picture (PiP) smoking: smoking content drivelive: live broadcasting in a running vehicle drug: drugs gamble: gambling If the scenes parameter is set to logo, the valid values are: normal: normal TV: controlled media logo trademark: trademark
rate	Float	99.1	The score of the confidence level. Valid values: 0 to 100. A higher confidence level indicates higher reliability of the moderation results. We recommend that you do not use this score in your business.

Table 5. audioScanResult
Parameter	Type	Example	Description
scene	String	antispam	The audio moderation scenario of the moderated video. The value is antispam.
label	String	customized	The category of the audio moderation result for the moderated video. Valid values: normal: normal spam: junk content ad: ad politics: political content terrorism: terrorist content abuse: abuse porn: pornographic content flood: excessive junk content contraband: prohibited content customized: custom content, such as a custom term
suggestion	String	block	The recommended subsequent operation. Valid values: pass: The moderation object does not require further actions. review: The moderation object contains suspected violations and requires manual review. block: The moderation object contains violations. We recommend that you delete or block the object.
rate	Float	99.91	The score of the confidence level. Valid values: 0 to 100. A greater value indicates a higher confidence level. If a value of pass is returned for the suggestion parameter, a higher confidence level indicates a higher probability that the content is normal. If a value of review or block is returned for the suggestion parameter, a higher confidence level indicates a higher probability that the content contains violations. Important We recommend that you use the values that are returned for the suggestion, label, and sublabel parameters to determine whether the content contains violations. The sublabel parameter is returned by specific operations.
details	JSONArray		The details about text in the moderated audio. The JSON array contains one or more elements. Each element corresponds to a text entry. For more information, see detail.

Table 6. detail
Parameter	Type	Example	Description
startTime	Integer	24	The start time of the text entry. Unit: seconds.
endTime	Integer	60	The end time of the text entry. Unit: seconds.
text	String	Computer	The content of the text entry that is converted from the audio.
label	String	normal	The category of the moderation result of the text entry. Valid values: normal: normal spam: junk content ad: ad politics: political content terrorism: terrorist content abuse: abuse porn: pornographic content flood: excessive junk content contraband: prohibited content customized: custom content, such as a custom term
keyword	String	On	The custom term hit by the text entry.
libName	String	Human	The name of the custom text library that contains the custom term hit by the text entry.

Table 7. logoData
Parameter	Type	Example	Description
type	String	TV	The type of the detected logo. For example, a value of TV indicates a controlled media logo.
name	String	***TV	The name of the detected logo.
x	Float	140	The distance between the upper-left corner of the logo area and the y-axis, with the upper-left corner of the image being the coordinate origin. Unit: pixel.
y	Float	68	The distance between the upper-left corner of the logo area and the x-axis, with the upper-left corner of the image being the coordinate origin. Unit: pixel.
w	Float	106	The width of the logo area. Unit: pixel.
h	Float	106	The height of the logo area. Unit: pixel.

Table 5. sfaceData
Parameter	Type	Example	Description
x	Float	444	The distance between the upper-left corner of the face area and the y axis, with the upper-left corner of the image being the coordinate origin.
y	Float	174	The distance between the upper-left corner of the face area and the x axis, with the upper-left corner of the image being the coordinate origin.
w	Float	467	The width of the face area.
h	Float	467	The height of the face area.
smileRate	Float	0	The probability of smiling.
glasses	Boolean	false	Indicates whether the person wears glasses.
faces	Array		The information about the recognized face. For more information about the structure, see the following table face.

Table 8. face
Parameter	Type	Example	Description
name	String	xxxx	The name of the person with the recognized face.
rate	Float	97.03	The probability that the detected face matches the recognized face.
id	String	AliFace_001****	The ID of the recognized face.

Table 9. hitLibInfo
Parameter	Type	Example	Description
context	String	xxxx	The custom text that the detected text hits.
libCode	String	69751	The code of the library that contains the custom text hit by the detected text.
libName	String	Human	The name of the library that contains the custom text hit by the detected text.

Table 10. hintWordsInfo
Parameter	Type	Example	Description
context	String	xxxx	The term that the detected text hits.

Examples

Sample requests

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

Sample success responses

Moderate only images in a video

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

Moderate both images and audio in a video

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