This topic describes the /green/image/scan operation that you can call to moderate images and obtain moderation results in real time. You can call this operation to moderate images for risky or illegal content. This operation is applicable to the following scenarios: pornography detection, terrorist content detection, ad violation detection, QR code detection, undesirable scene detection, and logo detection.

Operation description

Operation: /green/image/scan

You can call this operation to submit image moderation tasks and obtain moderation results in real time. 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.

  • Billing method:

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

  • Response timeout:

    The maximum response time that is allowed for a synchronous moderation request is 6s. If the moderation is not complete within 6s, a timeout error is returned. If you do not need to obtain moderation results in real time, you can send asynchronous moderation requests. In most cases, we recommend that you send synchronous moderation requests because synchronous moderation operations are easier to call. We recommend that you set the timeout period to 6s for calling synchronous moderation operations.

  • Return results:

    In general, moderation results are returned within 1s after you send a synchronous moderation request. The time may increase in special scenarios where a large number of requests are to be processed in the system, the size of images is large, or the images contain a large number of words.

  • Limits on images:
    • The images must use HTTP or HTTPS URLs.
    • The images must be in the PNG, JPG, JPEG, BMP, GIF, or WEBP format.
    • An image can be up to 20 MB in size. The limit for the image size is applicable to both synchronous and asynchronous moderation operations.
    • The duration for downloading an image is limited to 3s. If an image fails to be downloaded within 3s, a timeout error is returned.
    • We recommend that you submit images of at least 256 × 256 pixels to ensure the moderation effects.
    • The response time of an operation for moderating images varies based on the duration for downloading these images. Make sure that you use a stable and reliable storage service to store the images to be moderated. We recommend that you use Object Storage Service (OSS) or Content Delivery Network (CDN).
Table 1. Scenarios
Scenario Description Category of the moderation result
Pornography detection Detects pornographic or sexy content in images. normal, sexy, and porn
Terrorist content detection Detects terrorist or political content in images. normal, bloody, explosion, outfit, logo, weapon, politics, violence, crowd, parade, carcrash, flag, location, and others
Ad violation detection Detects ads or illegal text in images. normal, ad, politics, porn, abuse, terrorism, contraband, spam, npx, qrcode, and programCode
Note You can customize a policy for machine-assisted moderation and specify the categories that you want to detect based on actual requirements. For more information, see Customize policies for machine-assisted moderation.
QR code detection Detects QR codes or mini program codes in images. normal, qrcode, and programCode
Note You can customize a policy for machine-assisted moderation and specify the categories that you want to detect based on actual requirements. For more information, see Customize policies for machine-assisted moderation.
Undesirable scene detection Detects undesirable scenes, such as black screen, black edge, dark image, picture-in-picture, smoking, and live broadcasting in a running vehicle, in images. normal, meaningless, PIP, smoking, and drivelive
Logo detection Detects logos, such as TV station logos and trademarks, in images. normal, TV, and trademark

QPS limit

You can send up to 50 requests per second to call this operation by using your Alibaba Cloud account. If you send an excessive number of requests, throttling is implemented, and your business may be affected.

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.
scenes StringArray Yes ["porn","terrorism","ad","live","qrcode","logo"] The moderation scenario. Valid values:
  • porn: pornography detection
  • terrorism: terrorist content detection
  • ad: ad violation detection
  • qrcode: QR code detection
  • live: undesirable scene detection
  • logo: logo detection
You can specify multiple scenarios. For example, you can specify both porn and terrorism in the scenes parameter to detect pornographic and terrorist content.
Note If your moderation occurs in multiple scenarios at a time, you are charged the cumulative fee of all scenarios. The fee of each scenario equals the number of images that are moderated in the scenario multiplied by the unit price of the scenario.
tasks JSONArray Yes The list of moderation objects. Each element in the JSON array is a moderation task structure. The JSON array can contain a maximum of 100 elements. In other words, you can submit a maximum of 100 images at a time. To submit 100 images at a time, you must raise the relevant concurrency limit to a number greater than 100. For more information about the structure of each element, see task.
Table 2. task
Parameter Type Required Example Description
clientInfo JSONObject No null The information about the client. For more information, see the "Common request parameters" section of the Common parameters topic.
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 uuid-xxxx-xxxx-1234 The ID of the moderation object.

The ID can contain letters, digits, underscores (_), hyphens (-), and periods (.)and can be up to 128 characters in length. This ID uniquely identifies your business data.

url String Yes http://example.com/xxx.jpg The URL of the image to be moderated.
extras JSONObject No {"hitLibInfo":[{"context":"Haokan","libCode":"2144002","libName":"Text pattern library a"}]} The extra parameters that you can set for calling the operation. This parameter is not required for image moderation.
interval Integer No 2 The interval between two frames that are consecutively captured. This parameter is dedicated for GIF or long image moderation.
  • A GIF image can be regarded as an array of frames. One frame is captured for moderation from every n frames. The n is specified by the interval parameter. The system captures frames from GIF images only when this parameter is specified.
  • Long images can be in portrait or horizontal mode.
    • To moderate a long portrait image, in 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.
    • To moderate a long horizontal image, in 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.

By default, only the first frame of a GIF image or a long image is moderated. You can use the interval parameter to specify the interval between two frames that the system consecutively captures. This helps reduce moderation costs.

Note The interval and maxFrames parameters must be used in pairs. For example, the interval parameter is set to 2 and the maxFrames parameter is set to 10 for moderating a GIF image or a long image. In this example, one out of every two frames is moderated and a maximum of 10 frames are moderated. The fee is calculated based on the actual number of moderated frames.
maxFrames Integer No 10 The maximum number of frames to be captured. This parameter is dedicated for GIF or long image moderation. Default value: 1.

If the value of the interval parameter multiplied by that of the maxFrames parameter is smaller than the total number of frames in a GIF image or a 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 in the image by the value of the maxFrames parameter. This helps improve the overall moderation effects.

Response parameters

Parameter Type Example Description
code Integer 200 The returned HTTP status code.

For more information, see Common HTTP status codes.

msg String OK The message that is returned for the request.
dataId String uuid-xxxx-xxxx-1234 The ID of the moderation object.
Note If you set the dataId parameter in the moderation request, the dataId parameter is returned in the response.
taskId String img4wlJcb7p4wH4lAP3111111-123456 The ID of the image moderation task.
url String http://example.com/xxx.jpg The URL of the moderated image.
storedUrl String http://aliyundoc.com If you enable the feature of storing image evidence in Object Storage Service (OSS) buckets and the moderation task meets the configuration rule, the image is stored in your OSS bucket, and the corresponding HTTP URL is returned.
extras JSONObject {"hitLibInfo":[{"context":"Haokan","libCode":"2144002","libName":"Text pattern library a"}]} The additional information.

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

hitLibInfo: the information about the custom text library that the detected text in the moderated image hits. The value of this parameter is an array. For more information about the structure, see hitLibInfo.

results JSONArray The return results. If HTTP status code 200 is returned after a successful call, the array in the return results contains 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 Example Description
scene String porn The moderation scenario of the moderated image, which you specify in the moderation request. Valid values:
  • porn: pornography detection
  • terrorism: terrorist content detection
  • ad: ad violation detection
  • qrcode: QR code detection
  • live: undesirable scene detection
  • logo: logo detection
label String sexy The category of the moderation result of the moderated image. Valid values vary based on the specified moderation scenario.
  • If the scenes parameter is set to porn, the valid values are:
    • normal: normal
    • sexy: sexy 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 accident
    • flag: flag
    • location: landmark
    • others: other specified content
  • If the scenes parameter is set to ad, the valid values are:
    • normal: normal
    • ad: other ads
    • 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: illegal ad
    • qrcode: QR code
    • programCode: mini program code
  • If the scenes parameter is set to qrcode, the valid values are:
    • normal: normal
    • qrcode: QR code
    • programCode: mini program code
  • If the scenes parameter is set to live, the valid values are:
    • normal: normal
    • meaningless: no content in the image, such as black or white screen
    • PIP: small picture
    • smoking: smoking content
    • drivelive: live broadcasting in a running vehicle
  • If the scenes parameter is set to logo, the valid values are:
    • normal: normal
    • TV: TV station logo
    • trademark: trademark
sublabel String porn If the scenes parameter is set to porn or terrorism, the subcategory of the moderation result can be returned.

By default, this parameter is not returned. If you want this parameter to be returned, submit a ticket. This parameter can be returned only after it is configured by Alibaba Cloud engineers.

suggestion String block The recommended subsequent operation for you to perform. Valid values:
  • pass: The moderation object does not require further actions.
  • review: The moderation object contains suspected violations and requires human review.
  • block: The moderation object contains violations. We recommend that you delete or block the object.
rate Float 91.54 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.
Notice This score is for reference only. We recommend that you do not use this score in your business. 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 temporary access URL of each frame that is truncated from the moderated image because the image is too long. For more information about the structure, see frame.
hintWordsInfo JSONArray The information about the term that the detected ad or illegal text in the moderated image hits. For more information about the structure, see hintWordsInfo.
Note This parameter is applicable only to ad violation detection.
Example: 
"hintWordsInfo":[{"context":"Sensitive words"}]
qrcodeData StringArray ["http://example.com/01ZZOliO"] The information about the text that is included in the detected QR code in the moderated image.
Note This parameter is applicable only to QR code detection.
qrcodeLocations JSONArray The coordinate information about the detected QR code in the moderated image. For more information about the structure, see qrcodeLocation.
programCodeData JSONArray The location information about the detected mini program code in the moderated image. For more information about the structure, see programCodeData.
Note This parameter is applicable only to mini program code detection. Make sure that mini program code detection is enabled.
logoData JSONArray The information about the detected logo in the moderated image. For more information about the structure, see logoData.
Note This parameter is applicable only to logo detection.
sfaceData JSONArray The information about the detected terrorist content in the moderated image. For more information about the structure, see sfaceData.
Note This parameter is applicable only to terrorist content detection.
ocrData StringArray xxxx The information about the detected complete text in the moderated image.
Note By default, this parameter is not returned. If you want this parameter to be returned, submit a ticket.
Table 4. frame
Parameter Type Example Description
rate Float 89.85 The score of the confidence level. Valid values: 0 to 100. A higher confidence level indicates higher reliability of the moderation result. We recommend that you do not use this score in your business.
url String https://example.com/xxx-0.jpg The temporary access URL of the truncated frame. The URL is valid for 5 minutes.
Table 5. programCodeData
Parameter Type Example Description
x Float 11.0 The distance between the upper-left corner of the mini program code area and the y-axis, with the upper-left corner of the image being the coordinate origin. Unit: pixel.
y Float 0.0 The distance between the upper-left corner of the mini program code area and the x-axis, with the upper-left corner of the image being the coordinate origin. Unit: pixel.
w Float 402.0 The width of the mini program code area. Unit: pixel.
h Float 413.0 The height of the mini program code area. Unit: pixel.
Table 6. logoData
Parameter Type Example Description
type String TV The type of the detected logo. For example, a value of TV indicates the logo of a TV station.
name String xxx 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 7. sfaceData
Parameter Type Example Description
x Float 49 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. Unit: pixel.
y Float 39 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. Unit: pixel.
w Float 97 The width of the face area. Unit: pixel.
h Float 131 The height of the face area. Unit: pixel.
faces JSONArray [{"id":"AliFace_0001234","name":"Hit name","rate":91.54}] The information about the recognized face. The array contains the following parameters:
  • name: the name of the recognized face. The value is a string.
  • rate: The score of the confidence level. Valid values: 0 to 100. A greater value indicates a higher confidence level. A higher confidence level indicates higher reliability of the facial recognition result. The value is a floating-point number.
  • id: the ID of the recognized face. The value is a string.
Table 8. hitLibInfo
Parameter Type Example Description
context String xxxx The custom text that the detected text hits.
libCode String 123456 The code of the library that contains the custom text hit by the detected text.
libName String abc The name of the library that contains the custom text hit by the detected text.
Table 9. hintWordsInfo
Parameter Type Example Description
context String xxxx The term that the detected text hits.
Table 10. qrcodeLocation
Parameter Type Example Description
x Float 11.0 The distance between the upper-left corner of the QR code area and the y-axis, with the upper-left corner of the image being the coordinate origin. Unit: pixel.
y Float 0.0 The distance between the upper-left corner of the QR code area and the x-axis, with the upper-left corner of the image being the coordinate origin. Unit: pixel.
w Float 402.0 The width of the QR code area. Unit: pixel.
h Float 413.0 The height of the QR code area. Unit: pixel.
qrcode String http://xxx The URL in the detected QR code.

Examples

Sample requests 
{
    "scenes": [
        "porn",
        "terrorism",
        "ad",
        "live",
        "qrcode",
        "logo"
    ],
    "tasks": [
        {
            "dataId": "uuid-xxxx-xxxx-1234",
            "url": "http://example.com/xxx.jpg"
        }
    ]
}
Sample success responses 
{
     "msg": "OK",
     "code": 200,
     "data": [
          {
               "msg": "OK",
               "code": 200,
               "dataId": "uuid-xxxx-xxxx-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://example.com/0.ZZOliO",
                              "npx": "72.01",
                              "hitCustomLibCode": "8012345000",
                              "hitCustomLibName": "Name of the custom image library",
                              "hitLibInfo": [
                                   {
                                        "context": "Hit text",
                                        "libCode": "123456",
                                        "libName": "Name of the custom text library"
                            }
                        ]
                    },
                         "programCodeData": [
                              {
                                   "w": 402.0,
                                   "h": 413.0,
                                   "x": 11.0,
                                   "y": 0.0
                        }
                    ],
                         "frames": [
                              {
                                   "rate": 89.85,
                                   "url": "http://example.com/xxx-0.jpg"
                        },
                              {
                                   "rate": 68.06,
                                   "url": "http://example.com/xxx-1.jpg"
                        }
                    ],
                         "rate": 99.91,
                         "suggestion": "block",
                         "label": "ad",
                         "scene": "ad"
                },
                    {
                         "rate": 99.91,
                         "suggestion": "block",
                         "label": "drug",
                         "scene": "live"
                },
                    {
                         "qrcodeData": [
                              "http://example.com/01ZZOliO"
                    ],
                         "rate": 99.91,
                         "suggestion": "review",
                         "label": "qrcode",
                         "scene": "qrcode"
                },
                    {
                         "logoData": [
                              {
                                   "name": "xxx TV",
                                   "type": "TV",
                                   "x": 140,
                                   "y": 68,
                                   "w": 106,
                                   "h": 106
                        }
                    ],
                         "rate": 99.9,
                         "suggestion": "block",
                         "label": "TV",
                         "scene": "logo"
                }
            ],
               "taskId": "img4wlJcb7p4wH4lAP3111111-123456",
               "url": "http://example.com/xxx.jpg"
        }
    ],
     "requestId": "69B41AE8-1234-1234-1234-12D395695D2D"
}