This topic describes how to call an operation to submit synchronous 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 reference.

Description

Operation: /green/video/syncscan

You can call this operation to moderate videos for violations and obtain moderation results.
Note This operation only allows you to submit frames captured from a video for moderation. If you want to submit a video URL for moderation, call the /green/video/asyncscan operation.
This operation applies to the following video moderation scenarios: pornography detection, terrorist content detection, ad violation detection, undesirable scene detection, and logo detection.
Note You are charged for calling this operation. If you moderate a video in multiple scenarios at a time, the product of the number of video frames moderated in each scenario and the unit price in each scenario is summed up. For more information, see Pricing.

Parameters scenes and label

Before submitting 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.
Limits on frames captured from a video
  • The HTTP and HTTPS protocols can be used to access frames captured from a video.
  • Frames captured from a video must be in the formats of PNG, JPG, JPEG, BMP, GIF, and WEBP.
  • The size of a frame captured from a video can be up to 10 MB. If you have any special requirements, for example, moderating video frames greater than 10 MB in size, you can submit a ticket to raise the threshold.
  • The duration for downloading a frame captured from a video is limited to 3 seconds. If the duration exceeds 3 seconds, a download timeout error is returned.
  • We recommend that you submit video frames of at least 256×256 pixels to guarantee the moderation effects.
  • The response time of the /green/video/syncscan operation depends on the download duration of video frames. Make sure that the storage service for the video frames to be moderated is stable and reliable. We recommend that you use Alibaba Cloud Object Storage Service (OSS) or Content Delivery Network (CDN).

Request parameters

For more information about the common request parameters that must be included in all Content Moderation API requests, see Common request parameters.

The request body is a JSON object. The following table describes the parameters that the JSON object contains.

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 Content Moderation console. Alternatively, you can submit a ticket to ask us to help you create a business scenario.
scenes String array Yes The video moderation scenarios. Valid values:
  • porn: pornography detection
  • terrorism: terrorist content detection
  • ad: ad violation detection
  • live: undesirable scene detection
  • logo: logo detection
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 task.
Table 1. task
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.
frames JSON array Yes 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 frame.
framePrefix String No The prefix of the URLs of captured frames. The complete URL is in the format of framePrefix + frame.url.
Table 2. frame
Parameter Type Required Description
url String Yes The complete URL of the captured frame, in the format of framePrefix + url.
offset Integer No The interval between the start of the video and the captured frame. Unit: seconds.

Response parameters

For more information about common response parameters that this operation returns, see Common response parameters.

The data parameter in the response body is a JSON array. The following table describes the parameters that each element of the JSON array contains.

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 moderated video, which you specify in the dataId parameter of the moderation request.
taskId String Yes The ID of the moderation task.
results Array No The return results of the moderation task. If the HTTP status code 200 is returned to indicate 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 result.
Table 3. result
Parameter Type Required Description
scene String Yes The moderation scenario of the moderated video, which you specify in the moderation request.
label String Yes The category of moderation results for the moderated video in the specified moderation scenario. 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 are recommended, such as deleting or blocking the video.
rate Floating point Yes The probability that the moderated video falls into the detected category. Valid values: 0.00 to 100.00. A larger value indicates a higher probability that the video falls into this category.
frames JSON array No The moderation results of captured frames that fall into the detected category. For more information about the structure of the frame moderation result, see frame.
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 pattern library a"}]
hintWordsInfo Array No The information about the term 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 applies only to ad violation detection.
Example: 
"hintWordsInfo":[{"context":"Sensitive term"}]
logoData Array No The information about the logo detected in the moderated video. For more information about the structure, see logoData.
Note This parameter applies only 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 applies only to terrorist content detection and celebrity recognition.
Table 4. frame
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 moderation results for the captured frame. For more information about valid values, see Parameters scenes and label.
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 this category.
Table 5. 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 6. 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 7. 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 8. 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 9. hintWordsInfo
Parameter Type Required Description
context String Yes The term that the ad in the moderated video hits.

Examples

Sample requests 
{
  "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"
        }
      ]
    }
  ]
}
Sample success responses 
{
  "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",
          "frames":[
            {
              "offset":50,
              "url":"http://g1.ykimg.com/0B860000586C0A0300038A0460003",
              "label":"porn",
              "rate":99.1
            }
          ]
        }
      ]
    }
  ]
}