This topic describes how to call operations to submit asynchronous video moderation tasks and obtain moderation results. It intends to help you construct an HTTP call request.

  • For more information about how to construct an HTTP request, see Request Structure.
  • You can also select an existing HTTP request. For more information, see SDK overview.

Submit asynchronous video moderation tasks

Operation: /green/video/asyncscan

You can call this operation to moderate videos or video streams for violations asynchronously. This operation applies to the following video moderation scenarios: pornography detection, terrorist content detection, ad violation detection, undesirable scene detection, logo detection, and audio anti-spam.

Note You are charged for calling this operation. For more information about the billing method, see Pricing of Content Moderation.

If you moderate a video in multiple scenarios at a time, you are charged the cumulative fee of each scenario. The cumulative fee of each scenario equals the number of video frames moderated in the scenario multiplied by the unit price of the scenario. If you moderate the audio in the 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.

To obtain asynchronous moderation results, you can call the /green/video/results operation or enable callback notification. Content Moderation retains the moderation results for a maximum of 4 hours.

Parameters scenes and label

Before you submit a moderation task, you must set the scenes parameter to specify the moderation scenario. In the response, the label parameter indicates the category of moderation results in the specified moderation scenario. The following table lists the mapping between the scenes and label parameters in video moderation.
Scenario Description scenes label
Pornography detection Detects pornographic content in a video. porn
  • normal: The video is normal.
  • porn: The video contains pornographic content.
Terrorist content detection Detects terrorist content in a video. terrorism
  • normal: The video is normal.
  • terrorism: The video contains terrorist content.
Undesirable scene detection Detects undesirable scenes in a video. live
  • normal: The video is normal.
  • live: The video contains undesirable scenes.
Logo detection Detects specific logos in a video. logo
  • normal: The video is normal.
  • logo: The video contains logos.
Ad violation detection Detects ads or text violations in a video. ad
  • normal: The video is normal.
  • ad: The video contains ads.

Parameters audioScenes and label

If you submit a video moderation task and specify the video URL, you can moderate the audio in the video at the same time. To moderate the audio in a video, you must set the audioScenes parameter to specify the moderation scenario. In the response, the label parameter indicates the category of moderation results in the specified moderation scenario. The following table lists the mapping between the audioScenes and label parameters in audio anti-spam.
Scenario Description scenes label
Audio anti-spam Detects audio violations in a video.
Note By default, the audio to be moderated must be in Chinese. To moderate audio in English, submit a ticket to Alibaba Cloud technical support.
antispam
  • normal: The audio is normal.
  • spam: The audio contains junk content.
  • ad: The audio contains ads.
  • politics: The audio contains political content.
  • terrorism: The audio contains terrorist content.
  • abuse: The audio contains abuse.
  • porn: The audio contains pornographic content.
  • flood: The audio contains spam.
  • contraband: The audio contains prohibited content.
  • customized: The audio contains custom content. For example, the audio contains a custom keyword.
The videos to be moderated must meet the following requirements:
  • The videos must use HTTP or HTTPS URLs.
  • Video files must be in the following formats: AVI, FLV, MP4, MPG, ASF, WMV, MOV, WMA, RMVB, RM, FLASH, TS.
  • A single video can be up to 200 MB in size. If you have any special requirements, for example, moderating videos greater than 200 MB in size, you can submit a ticket to raise the threshold.
  • The video streams must be transferred through 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 video moderation task automatically ends.
  • The duration of a video moderation task depends 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 Alibaba Cloud Object Storage Service (OSS).

Request parameters

Parameter Type Required Description
bizType String No The business scenario. You can customize content moderation policies to apply different moderation standards or algorithm policies to different business scenarios. You can create a business scenario by specifying bizType in the Alibaba Cloud Content Moderation console. Alternatively, you can submit a ticket to ask Alibaba Cloud engineers to help you create a business scenario.
live Boolean No Specifies whether to moderate live streams. The default value is false, which indicates moderating videos but not live streams. To moderate live streams, you must set this parameter to true.
offline Boolean No Specifies whether to enable the nearline moderation mode.
  • The default value is false, which indicates the real-time moderation mode. In this mode, Content Moderation rejects moderation requests that exceed the concurrency limit.
  • If you set this parameter to true, the nearline moderation mode is enabled. 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 applies only to video moderation but not video stream moderation.
scenes String array Yes The video moderation scenario. Valid values:
  • porn: pornography detection
  • terrorism: terrorist content detection
  • ad: ad violation detection
  • live: undesirable scene detection
  • logo: logo detection
audioScenes String array No The audio moderation scenario. You can specify one or more audio moderation scenarios to moderate the audio in a video during video moderation. Set the value to antispam.
Note To moderate the audio in a video, you must specify the url parameter in the tasks parameter to submit the video URL. Audio moderation is inapplicable if you specify the frames parameter in the tasks parameter to submit frames captured from a video.
callback String No The callback URL for notifying you of asynchronous moderation results. HTTP and HTTPS URLs are supported. If you do not specify this parameter, you must poll moderation results at regular intervals.
seed String No The string used to generate a signature for the callback notification request. This parameter is required if you specify the callback parameter.
tasks JSON array Yes The list of video moderation tasks. Each element in the JSON array is a structure, that is, each element corresponds to a video. For more information about the structure of each element, see tasks.
Table 1. tasks
Parameter Type Required Description
clientInfo JSON structure No The information about the client. For more information, see the common query parameters in Common request parameters.
The server determines whether to use the global clientInfo parameter or the clientInfo parameter described in this table.
Note The clientInfo parameter described in this table takes a higher priority.
dataId String No The ID of the video to be moderated. Make sure that each ID is unique in a request.
url String No The URL of the video to be moderated. You must specify either this parameter or the frames parameter.
Note If you specify this parameter, you are charged for the video moderation task with the video URL submitted.
frames JSON array No The information about frames captured from the video. Each element in the JSON array of the frames parameter is a structure, that is, each element corresponds to a captured frame. For more information about the structure of each element, see frames.
Note If you specify this parameter, you are charged for the video moderation task with captured frames submitted.
framePrefix String No The prefix of the URL of a captured frame. If you specify the frames parameter, the complete URL of a captured video frame is in the format of framePrefix + frame.url.
interval Integer No The interval for capturing frames from the video. Unit: seconds. Valid values: 1 to 60. Default value: 1.
maxFrames Integer No The maximum number of frames that can be captured from the video. Valid values: 5 to 3600. Default value: 200. If you want to capture more frames from the video, submit a ticket.
Note
  • This parameter is only valid when you set the live parameter to false to moderate videos but not live streams. If you set the live parameter to true, the number of frames that can be captured from live streams is not restricted.
  • 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 for Media Processing, you can capture a maximum of 20,000 frames from the video. This method does not incur extra charges. For more information, see Authorize a role to access ApsaraVideo for Media Processing.
Table 2. frames
Parameter Type Required Description
url String No The URL of the captured frame. If you specify the framePrefix parameter, the complete URL of a captured frame is in the format of framePrefix + url.
offset Integer No The interval between the start of the video and the captured frame. Unit: seconds.

Callback notification

If you specify the callback parameter in the request, make sure that the HTTP or HTTPS URL specified in the callback parameter meets the following requirements: supports the POST method, uses UTF-8 to encode the transmitted data, and supports the checksum and content parameters. To call the operation to return the moderation result, Content Moderation sets the checksum and content parameters based on the generation rules and format described as follows.
Note The callback is successful only when the operation returns the HTTP status code 200. In case the callback fails, the operation tries to resend the moderation result to you for up to 16 times. If the callback fails for 16 times, the operation stops resending the moderation result. We recommend that you check the status of the callback URL.
Parameter Type Description
checksum String The string in the <UID> + <Seed> + <Content> format 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 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 cannot be the ID of a Resource Access Management (RAM) user.
content String The JSON-formatted string to be parsed to the callback data in JSON format. The format of the content parameter is described in the following section.
Example of the content parameter:
{
    "code": 200,
    "msg": "OK",
    "dataId": "videoId xxx",
    "taskId": "taskId xxx",
    "results": [
        {
            "label": "porn",
            "rate": 99.2,
            "scene": "porn",
            "suggestion": "block"
        }
    ]
}

Response parameters

Parameter Type Required Description
taskId String Yes The ID of the video moderation task.
dataId String No The ID of the moderation object.
Note If you specify the dataId parameter in the request, the dataId parameter is returned in the response.

Examples

Sample requests
  • Moderate frames captured from a video
    {
        "scenes": [
            "porn"
        ],
        "tasks": [
            {
                "dataId": "videoId xxx",
                "frames": [
                    {
                        "offset": 10,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460000"
                    },
                    {
                        "offset": 20,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460001"
                    },
                    {
                        "offset": 30,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460002"
                    },
                    {
                        "offset": 40,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460003"
                    },
                    {
                        "offset": 50,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A0460003"
                    },
                    {
                        "offset": 60,
                        "url": "http://g1.ykimg.com/0B860000586C0A0300038A046000x"
                    }
                ]
            }
        ]
    }
  • Moderate a video
    {
         "scenes": [
            "porn"
        ],
         "audioScenes": [
            "antispam"
        ],
         "tasks": [
              {
                   "dataId": "videoId xxx",
                   "url": "http://www.foo.bak/a.mp4",
                   "interval": 1,
                   "maxFrames": 200
            }
        ]
    }
  • Moderate a live stream
    {
        "scenes": [
            "porn"
        ],
        "live": true,
        "tasks": [
            {
                "dataId": "videoId xxx",
                "url": "http://www.foo.bak/a.flv",
                "interval": 1,
                "maxFrames": 200
            }
        ]
    }
Sample success responses
{
    "code": 200,
    "msg": "OK",
    "requestId": "requestID xxx",
    "data": [
        {
            "dataId": "videoId xxx",
            "taskId": "taskId xxx"
        }
    ]
}

Obtain asynchronous video moderation results

Operation: /green/video/results

You can call this operation to obtain asynchronous video moderation results. We recommend that you set the interval for obtaining the moderation results to 30 seconds. Content Moderation retains the moderation results for a maximum of 4 hours. If you set the interval to a value greater than 4 hours, the results will be deleted before you query them.

Note This operation is free of charge.

Request parameters

Parameter Type Required Description
body JSON array Yes The list of IDs of video moderation tasks you want to query. You can specify up to 100 task IDs.

Response parameters

Parameter Type Required Description
code Integer Yes The HTTP status code returned for the moderation task.
msg String Yes The message returned for the moderation task.
dataId String No The ID of the moderation object.
Note If you specify the dataId parameter in the request, the dataId parameter is returned in the response.
taskId String Yes The ID of the video moderation task.
results Array No The return results of the moderation task. If HTTP status code 200 is returned, indicating a successful call, the array in the return results may contain one or more elements. Each element is a structure. For more information about the structure of each element, see results.
Note In the scenario of moderating a video stream, HTTP status code 280 indicates that the moderation task is in progress, and HTTP status code 200 indicates that the moderation task is completed. If the moderation task is in progress, the returned moderation results contain all the issues that Content Moderation has detected in the task.
audioScanResults Structure No The audio moderation results. For more information about the structure, see audioScanResults.
Table 3. results
Parameter Type Required Description
scene String Yes The video moderation scenario, which is the same as the scenario that you specify in the moderation request.
label String Yes The category of the moderation result of the moderated video in the scenario specified by the scenes parameter. For more information about valid values, see Parameters scenes and label.
suggestion String Yes The machine-assisted moderation result of the moderated video. Valid values:
  • pass: The video is normal and does not require further actions, or the system does not detect the target content.
  • review: The video contains suspected violations and requires human review, or the system detects the target content.
  • block: The video contains violations. Further actions, for example, deleting or blocking the video, are recommended.
rate Floating point Yes The probability that the moderated video falls into the category indicated by the label parameter. Valid values: 0.00 to 100.00. A larger value indicates a higher probability that the video falls into the category.
frames JSON array No The moderation results (FrameScanResult) of captured frames that fall into the category. For more information about the structure of the frame moderation result, see frames.
extras JSON object No The additional information about the moderated video.

If you specify ad in the scenes parameter to detect ad violations, the extras parameter may return the following content:

hitLibInfo: the information about the custom text library that the ad in the moderated video hits. This parameter is of the array type. For more information about the structure, see hitLibInfo.

Example:
"hitLibInfo":[{"context":"Haokan","libCode":"2144002","libName":"Text library a"}]
hintWordsInfo Array No The information about the keyword that the ad in the moderated video hits. This parameter is of the array type. For more information about the structure, see hintWordsInfo.
Note This parameter only applies to ad violation detection.
Example:
"hintWordsInfo":[{"context":"Sensitive word"}]
logoData Array No The information about the logo detected in the moderated video. For more information about the structure, see logoData.
Note This parameter only applies to logo detection.
sfaceData Array No The information about the terrorist content detected in the moderated video. For more information about the structure, see sfaceData.
Note This parameter only applies to terrorist content detection and celebrity recognition.
Table 4. frames
Parameter Type Required Description
url String No The URL of the captured frame.
offset Integer No The interval between the start of the video and the captured frame. Unit: seconds.
label String Yes The category of the moderation result of the captured frame. For more information about valid values, see Parameter label for the captured frame.
rate Floating point Yes The probability that the captured frame falls into the category indicated by the label parameter. Valid values: 0.00 to 100.00. A larger value indicates a higher probability that the captured frame falls into the category.
Table 5. Parameter label for the captured frame
Scenario Description label
Pornography detection Detects pornographic content in the captured frame.
  • normal: The frame is normal.
  • sexy: The frame contains sexual content.
  • porn: The frame contains pornographic content.
Terrorist content detection Detects terrorist content in the captured frame.
  • normal: The frame is normal.
  • bloody: The frame contains bloody content.
  • explosion: The frame contains explosion and smoke.
  • outfit: The frame contains a special costume.
  • logo: The frame contains a logo.
  • weapon: The frame contains a weapon.
  • politics: The frame contains political content.
  • violence: The frame contains violence.
  • crowd: The frame contains a crowd.
  • parade: The frame contains a parade.
  • carcrash: The frame contains a car accident.
  • flag: The frame contains a flag.
  • location: The frame contains a landmark.
  • others: The frame contains other specified content.
Ad violation detection Detects ads or text violations in the captured frame.
  • normal: The frame is normal.
  • politics: The text contains political content.
  • porn: The text contains pornographic content.
  • abuse: The text contains abuse.
  • terrorism: The text contains terrorist content.
  • contraband: The text contains prohibited content.
  • spam: The text contains other junk content.
  • npx: The frame contains an illegal ad.
  • qrcode: The frame contains a QR code.
  • programCode: The frame contains an applet code.
  • ad: The frame contains other ads.
Note By default, only the normal or ad label is returned. If you want to use other labels, submit a ticket.
Undesirable scene detection Detects undesirable scenes in the captured frame.
  • normal: The frame is normal.
  • meaningless: The frame is meaningless.
  • PIP: The frame contains a small picture.
  • smoking: The frame contains smoking content.
  • drivelive: The frame shows live broadcasting while driving.
Logo detection Detects specific logos in the captured frame.
  • normal: The frame is normal.
  • TV: The frame contains a TV station logo.
  • trademark: The frame contains a trademark.
Table 6. logoData
Parameter Type Required Description
type String Yes The type of the detected logo. Example: TV, indicating the logo of a TV station.
name String Yes The name of the detected logo.
x Floating point Yes 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.
y Floating point Yes 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.
w Floating point Yes The width of the logo area.
h Floating point Yes The height of the logo area.
Table 7. sfaceData
Parameter Type Required Description
x Floating point Yes 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 Floating point Yes 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 Floating point Yes The width of the face area.
h Floating point Yes The height of the face area.
faces Array No The information about the face recognized in the moderated video. For more information about the structure, see face.
Table 8. face
Parameter Type Required Description
name String No The name of the person with the recognized face.
rate Floating point No The probability that the face detected in the moderated video hits the recognized face.
id String Yes The ID of the recognized face.
Table 9. audioScanResults
Parameter Type Required Description
scene String Yes The audio moderation scenario of the moderated video. The value is set to antispam.
label String Yes The category of the audio moderation result for the moderated video in the audio moderation scenario specified by the audioScenes parameter. For more information about valid values, see Parameters audioScenes and label.
suggestion String Yes The machine-assisted moderation result of the moderated audio. Valid values:
  • pass: The audio is normal and does not require further actions.
  • review: The audio contains suspected violations and requires human review.
  • block: The audio contains violations. Further actions, for example, deleting or blocking the audio, are recommended.
rate Floating point Yes The probability that the moderated audio falls into the category indicated by the label parameter. Valid values: 0.00 to 100.00. A larger value indicates a higher probability that the audio falls into the category.
details JSON array Yes The details about text in the moderated audio. The value is a JSON array that contains one or more elements. Each element corresponds to a piece of text. For more information, see details.
Table 10. details
Parameter Type Required Description
startTime Integer Yes The start time of the sentence in the audio. Unit: seconds.
endTime Integer Yes The end time of the sentence in the audio. Unit: seconds.
text String Yes The result of converting audio to text.
label String Yes The category of the moderation result of the text. For more information about valid values, see Parameters audioScenes and label.
keyword String No The custom keyword that the text hits.
libName String No The name of the custom text library that contains the custom keyword hit by the text.
Table 11. hitLibInfo
Parameter Type Required Description
context String No The custom text that the ad in the moderated video hits.
libCode String No The code of the library that contains the custom text hit by the ad in the moderated video.
libName String No The name of the library that contains the custom text hit by the ad in the moderated video.
Table 12. hintWordsInfo
Parameter Type Required Description
context String Yes The term that the ad in the moderated video hits.

Examples

Sample requests
[
    "taskId xxx",
    "taskId bbb"
]
Sample success responses
  • Detect only images in a video
    {
        "code": 200,
        "msg": "OK",
        "requestId": "requestID xxx",
        "data": [
            {
                "code": 200,
                "msg": "OK",
                "dataId": "videoId xxx",
                "taskId": "taskId xxx",
                "results": [
                    {
                        "label": "porn",
                        "rate": 99.2,
                        "scene": "porn",
                        "suggestion": "block"
                    }
                ]
            }
        ]
    }
  • Detect both images and audio in a video
    {
        "code": 200,
        "msg": "OK",
        "requestId": "requestID xxx",
        "data": [
            {
                "code": 200,
                "msg": "OK",
                "dataId": "videoId xxx",
                "taskId": "taskId xxx",
                "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": "blabla...",
                                "label": "customized"
                            },
                            {
                                "startTime": 24,
                                "endTime": 60,
                                "text": "blabla...",
                                "label": "normal"
                            }
                        ]
                    }
                ]
            }
        ]
    }