This topic describes the /green/image/asyncscan operation that you can call to asynchronously moderate images. 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.
Description about 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 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:
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 result query operation to query moderation results. For more information about the operation, see Description about the /green/image/results operation.
- 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).
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"] | The moderation scenario. Valid values:
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.
|
callback | String | No | http://example.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:
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 content when you enable callback
notification. Content Moderation encrypts the returned string based on the encryption
algorithm that you specify and then sends the encrypted string to the callback URL.
The returned string is in the UID + Seed + Content format. Valid values:
|
offline | Boolean | No | false | The moderation mode. Valid values:
|
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. |
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 | test4lNSMdggA0c56MMvfYoh4e-1mwxpx | 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 | https://img.alicdn.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png | The URL of the image to be moderated. |
extras | JSONObject | No | The extra parameters that you can set for calling 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.
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 are 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 |
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 | test4lNSMdggA0c56MMvfYoh4e-1mwxpx | 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 | fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695 | The ID of the moderation task. |
url | String | https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png | The URL of the moderation object. |
Examples
{
"scenes": [
"porn"
],
"tasks": [
{
"dataId": "test4lNSMdggA0c56MMvfYoh4e-1mwxpx",
"url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
}
]
}
{
"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://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
}
]
}
Description about 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 structure. 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 query moderation results at least 30s after you send an asynchronous moderation request 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 an hour. The default value of the offline parameter is false.
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 |
---|---|---|---|---|
body | JSONArray | Yes | ["fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"] | The list of IDs of asynchronous moderation tasks that you want to query. The array can contain up to 100 elements.
After you submit a moderation task, you can obtain the ID of the task from the response. |
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-xxx-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 moderation task. |
url | String | http://example.com/xxx.jpg | The URL of the moderation object. |
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. This parameter is of the array type. 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, see result. |
Parameter | Type | Example | Description |
---|---|---|---|
scene | String | terrorism | The moderation scenario of the moderated image, which you specify in the moderation
request. Valid values:
|
label | String | sexy | The category of the moderation result. Valid values vary based on the specified moderation
scenario.
|
sublabel | String | 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:
|
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 | {"hintWordsInfo":[{"context":"Sensitive words"}]} | The information about the term that the detected ad in the moderated image hits. This
parameter is of the array type. For more information about the structure, see hintWordsInfo.
Note This parameter is applicable only to ad violation detection.
|
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.
|
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 | http://example.com/xxx-0.jpg | The temporary access URL of the truncated frame. The URL is valid for 5 minutes. |
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. |
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. |
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:
|
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. |
Parameter | Type | Example | Description |
---|---|---|---|
context | String | xxxx | The term that the detected text hits. |
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
[
"fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695"
]
{
"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://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 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": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
"url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
}
],
"requestId": "69B41AE8-1234-1234-1234-12D395695D2D"
}