This topic describes the operation that you can call to synchronously moderate images for risky or illegal content and the involved parameters. It helps you construct HTTP requests for calling the corresponding operations to effectively detect different types of content violations in images.

  • 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/image/scan

You can call this operation to moderate images for illegal content and return the moderation result in real time.

This operation can be used to moderate images for pornographic content, terrorist content, ad violations, QR codes, undesirable scenes, and logos.

Parameters scenes and label

Before submitting a moderation request, you must specify the scenes parameter. You can specify multiple scenarios to detect different types of improper content in the same image.
Note If you moderate an image in multiple scenarios at a time, the product of the number of images moderated in each scenario and the unit price in each scenario is summed up.
In the moderation result, the label parameter indicates the category of moderation results in the specified moderation scenario. You can process images based on the return value of the suggestion parameter and determine the violation type based on the return value of the label parameter.
The following table lists the mapping between the scenes and label parameters in image moderation.
Scenario Description scenes label
Pornography detection Detects pornographic content in images. porn
  • normal: The image is normal and does not contain any pornographic content.
  • sexy: The image contains sexy content.
  • porn: The image contains pornographic content.
Terrorist content detection Detects terrorist content in images. terrorism
  • normal: The image is normal.
  • bloody: The image contains bloody content.
  • explosion: The image contains explosion and smoke.
  • outfit: The image contains a special costume.
  • logo: The image contains a logo.
  • weapon: The image contains a weapon.
  • politics: The image contains political content.
  • violence: The image contains violence.
  • crowd: The image contains a crowd.
  • parade: The image contains a parade.
  • carcrash: The image contains a car accident.
  • flag: The image contains a flag.
  • location: The image contains a landmark.
  • others: The image contains other specified content.
Ad violation detection Detects ads or illegal text in images. ad
  • normal: The image 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 image contains an illegal ad.
  • qrcode: The image contains a QR code.
  • programCode: The image contains an applet code.
  • ad: The image contains other ads.
Note By default, only the normal and ad tags can be returned. If you want to use other tags, submit a ticket.
QR code detection Detects QR codes in images. qrcode
  • normal: The image is normal.
  • qrcode: The image contains a QR code.
  • programCode: The image contains an applet code.
    Note By default, the programCode tag cannot be returned. If you want to use this tag, submit a ticket.
Undesirable scene detection Detects undesirable scenes, such as black screen, black edge, dark image, picture-in-picture, smoking, and violence, in images. live
  • normal: The image is normal.
  • meaningless: The image is meaningless.
  • PIP: The image contains a small picture.
  • smoking: The image contains smoking content.
  • drivelive: The image shows live broadcasting while driving.
Logo detection Detects logos, such as TV station logos and trademarks, in images. logo
  • normal: The image is normal.
  • TV: The image contains a TV station logo.
  • trademark: The image contains a trademark.

Limits on the response time

The maximum response time allowed for a synchronous request for image moderation is 6 seconds. If the moderation is not completed within 6 seconds, a timeout error is returned. If you do not have a high demand on getting the results in real time, you can send asynchronous requests to moderate images. In other cases, we recommend that you send synchronous requests for image moderation because it is easier to call the operations for synchronous image moderation. We recommend that you set the timeout period to 6 seconds for calling the operations for synchronous image moderation.

Limits on images
  • The HTTP and HTTPS protocols can be used to access images.
  • The images to be moderated must be in the formats of PNG, JPG, JPEG, BMP, GIF, and WEBP.
  • The size of an image can be up to 10 MB. This rule is applicable to both synchronous and asynchronous calls. If you have any special requirements, for example, moderating images greater than 10 MB in size, you can submit a ticket to raise the threshold.
  • The duration for downloading an image is limited to 3 seconds. If the duration exceeds 3 seconds, a download timeout error is returned.
  • We recommend that you submit images of at least 256×256 pixels to guarantee the moderation effects.
  • The response time of the /green/image/scan operation depends on the download duration of images. Make sure that the storage service for the images 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 image moderation scenarios. Valid values:
  • porn: pornography detection
  • terrorism: terrorist content detection
  • ad: ad violation detection
  • qrcode: QR code detection
  • live: undesirable scene detection
  • logo: logo detection
Note You can specify multiple moderation scenarios. For example, you can specify both porn and terrorism in the scenes parameter to detect pornographic content and terrorist content. The two scenarios are charged separately.
tasks JSON array Yes The image moderation object. Each element in a JSON array indicates an image moderation task. A maximum of 10 elements are supported in a JSON array, indicating that up to 10 images can be moderated in a JSON array. 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 image to be moderated. Make sure that each ID is unique in a request.
url String Yes The URL of the image to be moderated.
time Integer No The timestamp indicating the time when the image was created or edited. Unit: milliseconds.
extras Map No The extra parameters that are called.
interval Integer No The interval between two frames that are consecutively captured. This parameter is dedicated for GIF or long image moderation. A GIF image can be treated as an array of frames. One frame is extracted for test from every n frames, where n is specified by the parameter interval. The system captures frames from GIF images only when this parameter is specified. Long images can be in either portrait or horizontal mode.
  • For a long portrait image, of which the height is greater than 400 pixels and the ratio of height to width is greater than 2.5, you can divide the height by the width and round up the result to the nearest integer as the total number of frames.
  • For a long horizontal image, of which the width is greater than 400 pixels and the ratio of width to height is greater than 2.5, you can divide the width by the height and round up the result to the nearest integer as the total number of frames.
Note By default, only the first frame of a GIF or long image is moderated. Instead of having all the frames moderated, you can set the interval parameter to specify the interval between two frames that the system consecutively captures. This can help reduce costs. This parameter must be used together with maxFrames. Assume that interval is set to 2 and maxFrames is set to 100 for moderating a long image or GIF image. In this case, moderation is performed once for every two frames and a maximum of 100 frames can be moderated. The fee is calculated based on the actual number of moderated frames.
maxFrames Integer No The maximum number of frames to be captured. This parameter is dedicated for GIF or long image moderation. Default value: 1.

If the product of interval and maxFrames is smaller than the total number of frames in a GIF or long image, the interval for capturing frames is automatically changed to the integer rounded up from the result of dividing the total number of frames by maxFrames to improve the overall moderation effect.

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 image, which you specify in the dataId parameter of the moderation request.
taskId String Yes The ID of the moderation task.
url String Yes The URL in the corresponding request.
extras Map No The additional information about the moderated image.

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 image 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"}]
results Array No The return results. 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 2. result
Parameter Type Required Description
scene String Yes The moderation scenario of the moderated image, which you specify in the moderation request.
label String Yes The category of moderation results for the moderated image 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 image. Valid values:
  • pass: The image is normal and does not require further actions, or the system does not detect the target content.
  • review: The image contains suspected violations and requires human review, or the system detects the target content.
  • block: The image contains violations. Further actions are recommended, such as deleting or blocking the image.
rate Floating point Yes The probability that the moderated image falls into the detected category. Valid values: 0.00 to 100.00. A larger value indicates a higher probability that the image falls into this category.
frames Array No If the moderated image is truncated because it is too long, this parameter returns the temporary access URL of each truncated frame for your reference. For more information about the structure, see frames.
hintWordsInfo Array No The information about the term that the ad in the moderated image 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"}]
qrcodeData String array No The text information of all QR codes in the moderated image.
Note This parameter applies only to QR code detection.
programCodeData Array No The location information of the applet code in the moderated image. For more information about the structure, see programCodeData.
Note This parameter applies only to QR code detection. In addition, make sure that you have activated the applet code detection service by submitting a ticket to us.
logoData Array No The information about the logo detected in the moderated image. 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 image. For more information about the structure, see sfaceData.
Note This parameter applies only to terrorist content detection and celebrity recognition.
ocrData String array No The complete text information detected in the moderated image.
Note By default, this parameter is not returned. To return this parameter, submit a ticket.
Table 3. frames
Parameter Type Required Description
rate Floating point Yes The probability that the truncated frame falls into the detected category. This parameter is for reference only.
url String Yes The temporary access URL of the truncated frame. The URL is valid for 5 minutes.
Table 4. programCodeData
Parameter Type Required Description
x Floating point Yes The distance between the upper-left corner of the applet code 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 applet code 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 applet code area.
h Floating point Yes The height of the applet code area.
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 image. 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 image 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 image hits.
libCode String No The code of the library that contains the custom text hit by the ad in the moderated image.
libName String No The name of the library that contains the custom text hit by the ad in the moderated image.
Table 9. hintWordsInfo
Parameter Type Required Description
context String Yes The term that the ad in the moderated image hits.

Examples

Sample requests
{
  "scenes": ["porn", "terrorism", "ad", "live", "qrcode", "logo"],
  "tasks": [
    {
      "dataId": "uuid-xxxx-xxxx-1234",
      "url": "http://xxx.xxx.com/xxx.jpg"
    }
  ]
}
Sample success responses
{
  "msg": "OK",
  "code": 200,
  "data": [
    {
      "msg": "OK",
      "code": 200,
      "dataId": "uuid-xxxx-xxx-1234",
      "extras": {},
      "results": [
        {
          "rate": 99.63,
          "suggestion": "block",
          "label": "sexy",
          "scene": "porn"
        },
        {
          "label": "politics",
          "rate": 91.54,
          "scene": "terrorism",
          "sfaceData": [
            {
              "faces": [
                {
                  "id": "AliFace_0001234",
                  "name": "Hit name",
                  "rate": 91.54
                }
              ],
              "h": 131,
              "w": 97,
              "x": 49,
              "y": 39
            }
          ],
          "suggestion": "block"
        },
        {
          "extras": {
            "qrcodes": "http://xxxx.xxx.com/0.ZZOliO",
            "npx": "72.01",
            "hitCustomLibCode": "8012345000",
            "hitCustomLibName": "Name of the custom image library",
            "hitLibInfo": [
              {
                "context": "Hit text",
                "libCode": "123456",
                "libName": "Text library name"
              }
            ]
          },
          "programCodeData": [
            {
              "w": 402.0,
              "h": 413.0,
              "x": 11.0,
              "y": 0.0
            }
          ],
          "frames": [
            {
              "rate": 89.85,
              "url": "http://xxx.xxx.com/xxx-0.jpg"
            },
            {
              "rate": 68.06,
              "url": "http://xxx.xxx.com/xxx-1.jpg"
            }
          ],
          "rate": 99.91,
          "suggestion": "block",
          "label": "ad",
          "scene": "ad"
        },
        {
          "rate": 99.91,
          "suggestion": "block",
          "label": "drug",
          "scene": "live"
        },
        {
          "qrcodeData": [
            "http://xxx.xxx.com/01ZZOliO"
          ],
          "rate": 99.91,
          "suggestion": "review",
          "label": "qrcode",
          "scene": "qrcode"
        },
        {
          "logoData": [
            {
              "name": "xxx",
              "type": "TV",
              "x": 140,
              "y": 68,
              "w": 106,
              "h": 106
            }
          ],
          "rate": 99.9,
          "suggestion": "block",
          "label": "TV",
          "scene": "logo"
        }
      ],
      "taskId": "img4wlJcb7p4wH4lAP3111111-123456",
      "url": "http://xxx.xxx.xxx/xxx.jpg"
    }
  ],
  "requestId": "69B41AE8-1234-1234-1234-12D395695D2D"
}