/green/image/asyncscan and /green/image/results - Content Moderation

Asynchronously moderates images and queries moderation results. You can call the /green/image/asyncscan operation to moderate images for risky or illegal content and call the /green/image/results operation to query moderation results. These operations are 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 of the /green/image/asyncscan operation

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 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:
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 moderation results: When you submit asynchronous 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 moderation results at regular intervals: You do not need to set the callback parameter when you submit asynchronous moderation tasks. After you submit the tasks, you can call the /green/image/results operation to query moderation results. For more information about the operation, see Description of the /green/image/results operation.
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
Scenario	Description	Category of the moderation result
Pornography detection	Detects pornographic or sexy content in images.	normal, porn, and sexy
Terrorist content detection	Detects terrorist or political content in images.	normal, bloody, explosion, outfit, logo, weapon, politics, violence, crowd, parade, carcrash, flag, and location
Ad violation detection	Detects 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 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 the 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 (PiP), smoking, and live streaming while driving, 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 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


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"]	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 format of `["porn","terrorism"]` 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.
callback	String	No	http://www.aliyundoc.com	The callback URL for notifying you of asynchronous moderation results. HTTP and HTTPS URLs are supported. If you do not set this parameter, you must poll moderation results at regular intervals. If you set 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: a 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 Management 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 must be the ID of an Alibaba Cloud account, but not 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, the server sends HTTP status code 200 to Content Moderation. If your server fails to receive a callback notification, the server sends other HTTP status codes to Content Moderation. If your server fails to receive a callback notification, 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	abc_123	A random string that is used to generate a signature for the callback notification request. The string can be up to 64 characters in length and can contain letters, digits, and underscores (_). You can customize this string. It is used to verify the callback notification request when Content Moderation pushes callback notifications to your server. Note This parameter is required if you set the callback parameter.
cryptType	String	No	SHA256	The encryption algorithm used to encrypt the callback notification content when you enable callback notification. Content Moderation encrypts the returned string by using the encryption algorithm that you specify and sends the encrypted string to the callback URL. The returned string is in the `UID + Seed + Content` format. Valid values: SHA256: The HMAC-SHA256 encryption algorithm is used. This is the default value. SM3: The HMAC-SM3 encryption algorithm is used, and a hexadecimal string is returned. The string consists of lowercase letters and digits. For example, 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 is returned after you encrypt abc by using the HMAC-SM3 encryption algorithm.
offline	Boolean	No	false	Specifies whether to enable the nearline moderation mode or real-time moderation mode. Valid values: true: enables the nearline moderation mode. In this mode, the moderation tasks you submit may not be processed in real time, but can be queued for processing and will start within 24 hours. false: enables the real-time moderation mode. This is the default value. In this mode, Content Moderation rejects moderation requests beyond the concurrency limit.
tasks	JSONArray	Yes		The list of objects that you want to moderate. 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 objects at a time. To submit 100 objects 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	{"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.
dataId	String	No	test4lNSMdggA0c56MMvfYoh4e-1mwxpx	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.
url	String	Yes	https://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png	The HTTP or HTTPS URL that can be accessed over the Internet. The URL is up to 2,048 characters in length.
extras	JSONObject	No		The additional parameters that you can specify to call the operation. This parameter is not required for image moderation.
interval	Integer	No	1	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, 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 displayed 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 20 for moderating a GIF image or a long image. In this example, one out of every two frames is moderated and a maximum of 20 frames can be moderated. The fee is calculated based on the actual number of moderated frames.
maxFrames	Integer	No	20	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 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 error codes.
msg	String	OK	The message that is returned in response to the request.
dataId	String	test4lNSMdggA0c56MMvfYoh4e-1mwxpx	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.
taskId	String	fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695	The ID of the moderation task.
url	String	https://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png	The HTTP or HTTPS URL that can be accessed over the Internet. The URL is up to 2,048 characters in length.

Examples

Sample requests

http(s)://[Endpoint]/green/image/asyncscan
&<Common request parameters>
{
    "scenes": [
        "porn"
    ],
    "tasks": [
        {
            "dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
            "url": "https://www.aliyundoc.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://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ]
}

Description of the /green/image/results operation

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 syntax. You can also select an existing HTTP request. For more information, see SDK overview.

Billing method:
This operation is free of charge.
Response timeout:
We recommend that you set the query interval to 30 seconds. This way, you can query the moderation result 30 seconds after you submit the asynchronous image moderation task and obtain the value of the taskId parameter.
Note If you set the offline parameter to true, the validity period for the value of the taskId parameter is 24 hours. If you set the offline parameter to false, the validity period for the value of the taskId parameter is 1 hour. The default value of the offline parameter is false.