This topic describes how to call operations to submit asynchronous image moderation tasks and obtain moderation results. It intends to help you construct an HTTP call request to detect illegal or undesirable content in images from multiple dimensions.

  • 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.

Submit asynchronous image moderation tasks

Operation: /green/image/asyncscan

You can call this operation to moderate images for undesirable content asynchronously. This operation applies to the following image moderation scenarios: pornography detection, terrorist content detection, ad violation detection, QR code detection, undesirable scene detection, and logo detection.

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

Synchronous and asynchronous moderation

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

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

Parameters scenes and label

Before you submit a moderation task, you must set the scenes parameter to specify the moderation scenario. You can specify multiple moderation scenarios to detect different types of improper content in the same image. In the response, the label parameter indicates the category of moderation results in the specified moderation scenario. You can process images based on the value of suggestion in the response and determine the violation type based on the value of label in the response.
Note If you moderate images in multiple scenarios at a time, you are charged the cumulative fee of each scenario. The cumulative fee of each scenario equals the number of images moderated in the scenario multiplied by the unit price of the scenario.
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.
The images to be moderated must meet the following requirements:
  • The images must use HTTP or HTTPS URLs.
  • The images must be in the following formats: PNG, JPG, JPEG, BMP, GIF, or 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 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 guarantee 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 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 Alibaba Cloud Content Moderation console. Alternatively, you can submit a ticket to ask Alibaba Cloud engineers to help you create a business scenario.
scenes String array Yes The image 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
Note You can specify multiple scenarios for moderating a single image. For example, to detect pornographic and terrorist content in an image, you can specify the values porn and terrorism in the scenes parameter in the request.
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.
seed String No A random string 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 a structure, that is, each element corresponds to an image. For more information about the structure of each element, see tasks.
Table 1. tasks
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.
extras Map No The extra parameters for calling the operation.
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 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 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 moderation costs. This parameter must be used together with the maxFrames parameter. Assume that the interval parameter is set to 2 and the maxFrames parameter is set to 100 for moderating a GIF or long image. In this case, one out of every two frames is moderated 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 value of multiplying the interval by 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 in the image by maxFrames. This helps improve the overall moderation effect.

Callback notification

If you specify the callback parameter in the request, make sure that the HTTP or HTTPS URL specified in the callback parameter meets the following requirements: supports the POST method, uses UTF-8 to encode the transmitted data, and supports the checksum and content parameters. To call the operation to return the moderation result, Content Moderation sets the checksum and content parameters based on the generation rules and format described as follows.
Note The callback is successful only when the operation returns the HTTP status code 200. In case the callback fails, the operation tries to resend the moderation result to you for up to 16 times. If the callback fails for 16 times, the operation stops resending the moderation result. We recommend that you check the status of the callback URL.
Parameter Type Description
checksum String The string in the <UID> + <Seed> + <Content> format 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 Resource Access Management (RAM) user.
content String The JSON-formatted string to be parsed to the callback data in JSON format. The format of the content parameter is described in the following section.
Example of the content parameter:
{
    "code": 200,
    "msg": "OK",
    "dataId": "imageId xxx",
    "taskId": "taskId xxx",
    "results": [
        {
            "label": "porn",
            "rate": 99.2,
            "scene": "porn",
            "suggestion": "block"
        }
    ]
}

Response parameters

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 in the moderation request.
taskId String Yes The ID of the image moderation task.
url String Yes The URL of the moderated image, which you specify in the url parameter in the moderation request.

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"
        }
    ]
}

Obtain asynchronous image moderation results

Operation: /green/image/results

You can call this operation to obtain asynchronous image moderation results. We recommend that you set the interval for obtaining the moderation results to 30 seconds. Content Moderation retains the moderation results for a maximum of 1 hour. If you set the interval to a value greater than 1 hour, the results will be deleted before you query them.

Note This operation is free of charge.

Request parameters

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

Response parameters

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 in the moderation request.
taskId String Yes The ID of the image moderation task.
url String No The URL of the moderated image, which you specify in the url parameter in the moderation 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 library a"}]
results Array No The return results of the moderation task. If HTTP status code 200 is returned, indicating 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 results.
Table 2. results
Parameter Type Required Description
scene String Yes The image moderation scenario, which is the same as the scenario that you specify in the moderation request.
label String Yes The category of the moderation result of the moderated image in the scenario specified by the scenes parameter. 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, for example, deleting or blocking the image, are recommended.
Note In the scenario of QR code detection, the suggestion parameter only indicates whether the image contains a QR code.
rate Floating point Yes 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 the category.
frames Array No If the moderated image is truncated because it is too long, this parameter returns the temporary URL of each truncated frame. For more information about the structure, see frames.
hintWordsInfo Array No The information about the keyword 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 only applies to ad violation detection.
Example:
"hintWordsInfo":[{"context":"Sensitive word"}]
qrcodeData String array No The information about the text included in all QR codes in the moderated image.
Note This parameter only applies to QR code detection.
programCodeData Array No The location information about the applet code in the moderated image. For more information about the structure, see programCodeData.
Note This parameter only applies to QR code detection. If you want Content Moderation to return this parameter, submit a ticket to enable applet code detection.
logoData Array No The information about the logo detected in the moderated image. For more information about the structure, see logoData.
Note This parameter only applies 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 only applies to terrorist content detection and celebrity recognition.
ocrData String array No The information about the complete text detected in the moderated image.
Note By default, Content Moderation does not return this parameter. If you want Content Moderation 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
[
    "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"
]
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": "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": "img4wlJcb7p4wH4lAP3111111-123456",
               "url": "http://xxx.xxx.xxx/xxx.jpg"
        }
    ],
     "requestId": "69B41AE8-1234-1234-1234-12D395695D2D"
}