This topic describes the /green/image/asyncscan operation that you can call to asynchronously moderate images for risky and 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.

Scenarios

Scenario Description Category of the moderation result
Pornography detection Detects pornographic content in images. normal, sexy, and porn
Terrorist content detection Detects terrorist 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 By default, you can use only the normal and ad categories. If you want to use other categories, submit a ticket.
QR code detection Detects QR codes or applet codes in images. normal, qrcode, and programCode
Note By default, you can use only the normal and qrcode categories. If you want to use the programCode category, submit a ticket.
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

Submit asynchronous image moderation tasks

Operation: /green/image/asyncscan

You can call this operation to submit asynchronous image moderation tasks. 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 time:

    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 other 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:

    If you send asynchronous moderation requests, the moderation results are not returned in real time. To obtain moderation results, you can poll the moderation results at regular intervals or enable callback notification. The moderation results are retained for up to 1 hour.

    • Enable callback notification to obtain image moderation results: When you submit asynchronous image moderation tasks, you can specify a callback URL for receiving moderation results in the callback parameter of the moderation request. For more information about the callback parameter, see Request parameters.
    • Poll image moderation results at regular intervals: You do not need to specify the callback parameter when you submit asynchronous image moderation tasks. After you submit the tasks, you can call the /green/image/results operation to query moderation results. For more information about the /green/image/results operation, see Query asynchronous image moderation results.
  • 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 10 MB in size. This rule is applicable to both synchronous and asynchronous moderation operations. If you have special requirements, for example, you want to moderate images larger than 10 MB in size, submit a ticket to raise the threshold.
    • 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 depends 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 Alibaba Cloud Object Storage Service (OSS) or Content Delivery Network (CDN).

Request parameters

Parameter Type Required Description
bizType String No The business scenario. You can create a business scenario in the Alibaba Cloud Content Moderation console. For more information, see Customize policies for machine-assisted moderation. Alternatively, you can submit a ticket to ask Alibaba Cloud engineers to help you create a business scenario.
scenes String array Yes 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 moderation scenarios. For example, you can specify both porn and terrorism in the scenes parameter to detect pornographic and terrorist content.
Note If you moderate images 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.
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.
If you specify the callback parameter in the moderation request, make sure that the specified HTTP or HTTPS URL meets the following requirements: supports the POST method, uses UTF-8 to encode the transmitted data, and supports the checksum and content parameters. To send moderation results to the specified callback URL, Content Moderation returns the checksum and content parameters in callback notifications based on the following rules and format:
  • checksum: The string in the UID + Seed + Content format that is 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 RAM user.
  • content: The JSON-formatted string to be parsed to the callback data in the JSON format. For more information about the format of the content parameter, see the sample success responses of each operation that you can call to query asynchronous moderation results.
Note If your server receives a callback notification, it sends HTTP status code 200 to Content Moderation. If your server fails to receive a callback notification, it sends other HTTP status codes to Content Moderation. After Content Moderation receives an HTTP status code other than 200, Content Moderation continues to push the callback notification until your server receives it. Content Moderation can push a callback notification repeatedly for up to 16 times. After 16 times, Content Moderation stops pushing the callback notification. In this case, we recommend that you check the status of the callback URL.
seed String No A random string that is 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 image moderation tasks. Each element in the JSON array is an image moderation task structure, namely, each element corresponds to an image. 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" section of the Common request 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 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.
extras JSON structure No The extra parameters that you can specify for calling the operation. The extras parameter is not required for image moderation.
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 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.
    • 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.

By default, only the first frame of a GIF image or a long image is moderated. Instead of having all the frames 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. Assume that the interval parameter is set to 2 and the maxFrames parameter is set to 100 for moderating a GIF image or a long image. In this case, one out of every two frames is moderated and a maximum of 100 frames are 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 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 Description
code Integer The HTTP status code returned for the image moderation task.
msg String The message returned for the image moderation task.
dataId String The ID of the moderation object.
Note If you specify the dataId parameter in the moderation request, the dataId parameter is returned in the response.
taskId String The ID of the image moderation task.
url String The URL of the moderated image.

Examples

Sample requests
{
    "scenes": [
        "porn"
    ],
    "tasks": [
        {
            "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
            "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ]
}
Sample success responses
{
    "code": 200,
    "msg": "OK",
    "requestId": "95AD868A-F5D2-4AEA-96D4-E0273B8E074C",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
            "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
            "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ]
}

Query asynchronous image moderation results

Operation: /green/image/results

You can call this operation to query asynchronous image moderation results. 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:

    This operation is free of charge.

  • Response time:

    We recommend that you query moderation results at least 30s after you send an asynchronous moderation request. Content Moderation retains moderation results for up to 4 hours. If you query moderation results after 4 hours, the results are deleted.

Request parameters

Parameter Type Required Description
body JSON array Yes The list of IDs of asynchronous moderation tasks that you want to query. You can specify up to 1,000 task IDs.

Response parameters

Parameter Type Description
code Integer The HTTP status code returned for the image moderation task.
msg String The message returned for the image moderation task.
dataId String The ID of the moderation object.
Note If you specify the dataId parameter in the moderation request, the dataId parameter is returned in the response.
taskId String The ID of the image moderation task.
url String The URL of the moderated image.
extras JSON structure The additional information about the moderated image.

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 ad or illegal text 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 The return results of the image moderation task. 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 2. result
Parameter Type Description
scene String 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 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 of the label parameter are:
    • normal: The image does not contain sexy or pornographic content.
    • sexy: The image contains sexy content.
    • porn: The image contains pornographic content.
  • If the scenes parameter is set to terrorism, the valid values of the label parameter are:
    • normal: The image does not contain terrorist content.
    • 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.
  • If the scenes parameter is set to ad, the valid values of the label parameter are:
    Note By default, only normal and ad can be returned. If you want to use other categories, submit a ticket.
    • normal: The image does not contain ads or illegal text.
    • ad: The image contains other ads.
    • 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 junk content.
    • npx: The image contains an illegal ad.
    • qrcode: The image contains a QR code.
    • programCode: The image contains an applet code.
  • If the scenes parameter is set to qrcode, the valid values of the label parameter are:
    Note By default, programCode cannot be returned. If you want to use this category, submit a ticket.
    • normal: The image does not contain QR codes or applet codes.
    • qrcode: The image contains a QR code.
    • programCode: The image contains an applet code.
  • If the scenes parameter is set to live, the valid values of the label parameter are:
    • normal: The image does not contain undesirable scenes.
    • meaningless: The image is meaningless, such as black or white screen.
    • PIP: The image contains a small picture.
    • smoking: The image contains smoking content.
    • drivelive: The image shows live broadcasting in a running vehicle.
  • If the scenes parameter is set to logo, the valid values of the label parameter are:
    • normal: The image does not contain logos.
    • TV: The image contains a TV station logo.
    • trademark: The image contains a trademark.
sublabel String
suggestion String The machine-assisted moderation result of the moderated image. Valid values:
  • pass: The image does not require further actions.
  • review: The image contains suspected violations and requires human review.
  • block: The image contains violations. We recommend that you delete or block the image.
rate Floating point The probability that the moderated image 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 image falls into this category.
frames Array 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 Array 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 String array 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.
programCodeData Array The location information about the detected applet code in the moderated image. For more information about the structure, see programCodeData.
Note This parameter is applicable only to applet code detection. Make sure that applet code detection is enabled.
logoData Array 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 Array 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 String array The information about the detected complete text in the moderated image.
Note By default, this parameter is not returned. If this parameter needs to be returned, submit a ticket.
Table 3. frame
Parameter Type Description
rate Floating point The confidence level. This parameter is only for reference.
url String The temporary access URL of the truncated frame. The URL is valid for 5 minutes.
Table 4. programCodeData
Parameter Type Description
x Floating point 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. Unit: pixels.
y Floating point 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. Unit: pixels.
w Floating point The width of the applet code area. Unit: pixels.
h Floating point The height of the applet code area. Unit: pixels.
Table 5. logoData
Parameter Type Description
type String The type of the detected logo. For example, a value of TV indicates the logo of a TV station.
name String The name of the detected logo.
x Floating point 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: pixels.
y Floating point 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: pixels.
w Floating point The width of the logo area. Unit: pixels.
h Floating point The height of the logo area. Unit: pixels.
Table 6. sfaceData
Parameter Type Description
x Floating point 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: pixels.
y Floating point 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: pixels.
w Floating point The width of the face area. Unit: pixels.
h Floating point The height of the face area. Unit: pixels.
faces Array The information about the recognized face in the moderated image. The array contains the following parameters:
  • name: the name of the recognized face that is detected in the moderated image. The value is a string.
  • rate: the probability that the detected face in the moderated image hits the recognized face. The value is a floating-point number.
  • id: the ID of the recognized face. The value is a string.
Table 7. hitLibInfo
Parameter Type Description
context String The custom text that the detected ad or illegal text in the moderated image hits.
libCode String The code of the library that contains the custom text hit by the detected ad or illegal text in the moderated image.
libName String The name of the library that contains the custom text hit by the detected ad or illegal text in the moderated image.
Table 8. hintWordsInfo
Parameter Type Description
context String The term that the detected ad or illegal text in the moderated image hits.

Examples

Sample requests
[
    "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"
]
Sample success responses
{
     "msg": "OK",
     "code": 200,
     "data": [
          {
               "msg": "OK",
               "code": 200,
               "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
               "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": "Name of the text library"
                            }
                        ]
                    },
                         "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 TV",
                                   "type": "TV",
                                   "x": 140,
                                   "y": 68,
                                   "w": 106,
                                   "h": 106
                        }
                    ],
                         "rate": 99.9,
                         "suggestion": "block",
                         "label": "TV",
                         "scene": "logo"
                }
            ],
               "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
               "url": "https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ],
     "requestId": "69B41AE8-1234-1234-1234-12D395695D2D"
}