Moderates images and obtains 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, quick response (QR) code detection, undesirable scene detection, and logo detection.

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 syntax. 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 methods, see Content Moderation Pricing.

  • Response timeout:

    The maximum response time that is allowed for a synchronous moderation request is 6 seconds. If the moderation is not completed within 6 seconds, 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 6 seconds for calling synchronous moderation operations.

  • Returned results:

    In general, moderation results are returned within 1 second 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 URLs of images must be 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 3 seconds. If an image fails to be downloaded within 3 seconds, 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
ScenarioDescriptionCategory of the moderation result
Pornography detectionDetects pornographic or sexy content in images. normal, porn, and sexy
Terrorist content detectionDetects terrorist or political content in images. normal, bloody, explosion, outfit, logo, weapon, politics, violence, crowd, parade, carcrash, flag, and location
Ad violation detectionDetects ads or violation text in images. normal, politics, porn, abuse, terrorism, contraband, spam, npx, qrcode, programCode, and ad
Note You can customize a policy for machine-assisted moderation and specify the categories that you want to detect based on the actual requirements. For more information, see Customize policies for machine-assisted moderation.
QR code detectionDetects 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 the actual requirements. For more information, see Customize policies for machine-assisted moderation.
Undesirable scene detectionDetects undesirable scenes, such as black screen, black edge, dark image, Picture-in-Picture (PiP), smoking, and live streaming while driving, in images. normal, meaningless, PIP, smoking, and drivelive
Logo detectionDetects logos, such as TV station logos and trademarks, in images. normal, TV, and trademark

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

ParameterTypeRequiredExampleDescription
bizTypeStringNodefaultThe business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize policies for machine-assisted moderation.
scenesStringArrayYes["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 you specify multiple scenarios for moderation 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.
tasksJSONArrayYesThe list of moderation tasks that you want to submit. 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 tasks at a time. To submit 100 tasks 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 2. task
ParameterTypeRequiredExampleDescription
clientInfoJSONObjectNo{"userId":"12023****","userNick":"Mike","userType":"others"}

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.
dataIdStringNocfd33235-71a4-468b-8137-a5ffe323****The ID of the moderated 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.

urlStringYeshttp://www.aliyundoc.com/xxx.jpg

The HTTP or HTTPS URL that can be accessed over the Internet. The URL is up to 2,048 characters in length.

extrasJSONObjectNo{"hitLibInfo":[{"context":"Haokan","libCode":"2144002","libName":"Text pattern library a"}]}The additional parameters that you can specify to call the operation. This parameter is not required for image moderation.
intervalIntegerNo2The interval between two frames that are consecutively captured. This parameter is used to perform 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, where 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, you can calculate the total number of frames in the following way: divide the height by the width and round the result to the nearest integer. In a long portrait image, the height is greater than 400 pixels, and the ratio of height to width is greater than 2.5.
    • To moderate a long horizontal image, you can calculate the total number of frames in the following way: divide the width by the height and round the result to the nearest integer. In a long horizontal image, the width is greater than 400 pixels, and the ratio of width to height is greater than 2.5.

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 together. 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 can be moderated. The fee is calculated based on the actual number of moderated frames.
maxFramesIntegerNo10The 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 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

ParameterTypeExampleDescription
codeInteger200The returned HTTP status code.

For more information, see Common error codes.

msgStringOKThe message that is returned in response to the request.
dataIdStringcfd33235-71a4-468b-8137-a5ffe323****The ID of the moderated object.
Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here.
taskIdStringimg4wlJcb7p4wH4lAP3111111-123456The ID of the moderation task.
urlStringhttp://www.aliyundoc.com/xxx.jpg

The HTTP or HTTPS URL that can be accessed over the Internet. The URL is up to 2,048 characters in length.

storedUrlStringhttp://www.aliyundoc.comThe HTTP URL of the Object Storage Service (OSS) bucket that stores image evidence. If you enable the feature of storing image evidence in OSS buckets, images that match the evidence storage rule are stored in the specified OSS bucket.
extrasJSONObject{"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 hit by the text detected in the moderated image. This parameter is of the array type. For more information about the structure, see hitLibInfo.

resultsJSONArrayThe moderation results. If the call is successful, the HTTP status code 200 and moderation results are returned. The array of moderation 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
ParameterTypeExampleDescription
sceneStringpornThe image moderation scenario that you specified 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
labelStringsexyThe category of the moderation result. Valid values:
  • 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: special 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 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: overlay 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: picture-in-picture
    • smoking: smoking
    • drivelive: streaming during driving
    • drug: drugs
    • gamble: gambling
  • If the scenes parameter is set to logo, the valid values are:
    • normal: normal
    • TV: logo of banned media
    • trademark: trademark
sublabelStringpornIf the scenes parameter is set to porn or terrorism, the subcategory of the moderation result can be returned in this parameter.

By default, this parameter is not returned. If you want this parameter to be returned,

suggestionStringblockThe recommended subsequent operation. Valid values:
  • pass: The moderated object does not require further actions.
  • review: The moderated object contains suspected violations and requires manual review.
  • block: The moderated object contains violations. We recommend that you delete or block the object.
rateFloat91.54The 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.
framesJSONArrayIf the moderated image is too long, the image is truncated. This parameter returns the temporary URL of each frame in the truncated image. For more information about the structure, see frame.
hintWordsInfoJSONArrayThe information about the term hit by the ad or violation text detected in the moderated image. For more information about the structure, see hintWordsInfo.
Note This parameter is applicable only to ad violation detection.
Example: 
"hintWordsInfo":[{"context":"Sensitive words"}]
qrcodeDataStringArray["http://www.aliyundoc.com/01ZZOliO"]The information about the text that is included in the QR code detected in the moderated image.
Note This parameter is applicable only to QR code detection.
qrcodeLocationsJSONArrayThe coordinate information of the QR code detected in the moderated image. For more information about the structure, see qrcodeLocation.
programCodeDataJSONArrayThe location information of the mini program code detected 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.
logoDataJSONArrayThe information about the logo detected in the moderated image. For more information about the structure, see logoData.
Note This parameter is applicable only to logo detection.
sfaceDataJSONArrayThe information about the terrorist content detected in the moderated image. For more information about the structure, see sfaceData.
Note This parameter is applicable only to terrorist content detection.
ocrDataArrayHaokanThe information about the complete text detected in the moderated image.
Note By default, this parameter is not returned.
Table 4. frame
ParameterTypeExampleDescription
rateFloat89.85The 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.
urlStringhttp://www.aliyundoc.com/xxx-0.jpgThe temporary URL of the frame in the truncated image. The URL is valid for 5 minutes.
Table 5. programCodeData
ParameterTypeExampleDescription
xFloat11.0The 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.
yFloat0.0The 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.
wFloat402.0The width of the mini program code area. Unit: pixel.
hFloat413.0The height of the mini program code area. Unit: pixel.
Table 6. logoData
ParameterTypeExampleDescription
typeStringTVThe type of the detected logo. For example, a value of TV indicates a logo of banned media.
nameStringxxx TVThe name of the detected logo.
xFloat140The 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.
yFloat68The 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.
wFloat106The width of the logo area. Unit: pixel.
hFloat106The height of the logo area. Unit: pixel.
Table 7. sfaceData
ParameterTypeExampleDescription
xFloat49The 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.
yFloat39The 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.
wFloat97The width of the face area. Unit: pixel.
hFloat131The height of the face area. Unit: pixel.
facesJSONArray[{"name":"Hit name","rate":91.54,"id":"AliFace_0123****"}]The information about the recognized faces. Each element in the array contains the following parameters:
  • name: the name of the person with 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
ParameterTypeExampleDescription
contextStringHaokanThe custom term hit by the detected text.
libCodeString123456The code of the library that contains the custom term hit by the detected text.
libNameStringabcThe name of the library that contains the custom term hit by the detected text.
Table 9. hintWordsInfo
ParameterTypeExampleDescription
contextStringHaokanThe term hit by the detected text.
Table 10. qrcodeLocation
ParameterTypeExampleDescription
xFloat11.0The 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.
yFloat0.0The 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.
wFloat402.0The width of the QR code area. Unit: pixel.
hFloat413.0The height of the QR code area. Unit: pixel.
qrcodeStringhttp://www.aliyundoc.com/0.ZZOliOThe URL that the detected QR code points to.

Examples

Sample requests 
http(s)://[Endpoint]/green/image/scan
&<Common request parameters>
{
    "scenes": [
        "porn",
        "terrorism",
        "ad",
        "live",
        "qrcode",
        "logo"
    ],
    "tasks": [
        {
            "dataId": "uuid-xxxx-xxxx-1234",
            "url": "http://www.aliyundoc.com/xxx.jpg"
        }
    ]
}
Sample success responses 
{
     "msg": "OK",
     "code": 200,
     "data": [
          {
               "msg": "OK",
               "code": 200,
               "dataId": "cfd33235-71a4-468b-8137-a5ffe323****",
               "extras": {

            },
               "results": [
                    {
                         "rate": 99.63,
                         "suggestion": "block",
                         "label": "sexy",
                         "scene": "porn"
                },
                    {
                         "label": "politics",
                         "rate": 91.54,
                         "scene": "terrorism",
                         "sfaceData": [
                              {
                                   "faces": [
                                        {
                                             "id": "AliFace_0123****",
                                    "name": "Hit name",
                                             "rate": 91.54
                                }
                            ],
                                   "h": 131,
                                   "w": 97,
                                   "x": 49,
                                   "y": 39
                        }
                    ],
                         "suggestion": "block"
                },
                    {
                         "extras": {
                              "qrcodes": "http://www.aliyundoc.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://www.aliyundoc.com/xxx-0.jpg"
                        },
                              {
                                   "rate": 68.06,
                                   "url": "http://www.aliyundoc.com/xxx-1.jpg"
                        }
                    ],
                         "rate": 99.91,
                         "suggestion": "block",
                         "label": "ad",
                         "scene": "ad"
                },
                    {
                         "rate": 99.91,
                         "suggestion": "block",
                         "label": "drug",
                         "scene": "live"
                },
                    {
                         "qrcodeData": [
                              "http://www.aliyundoc.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://www.aliyundoc.com/xxx.jpg"
        }
    ],
     "requestId": "69B41AE8-1234-1234-1234-12D395695D2D"
}