This topic describes how to call the file moderation API to make HTTP requests.
Usage notes
The /green/file/asyncscan API operation is used for asynchronous file moderation 1.0.
You can submit a file moderation task. The system then automatically parses the file content and moderates the images and text within it.
The usage and pricing for this feature are the same as for image moderation and text moderation. Text moderation is billed per request, and each request can moderate up to 5,000 characters. Image moderation is billed based on the number of images.
- Supported file types:
- Text content can be moderated in the following file types:
PDF, WORD, TXT, PPT, EXCEL, OUTLOOK, VISIO, ZIP, TAR, and RTF.
- Image content can be moderated in PDF files.
- Text content can be moderated in the following file types:
- Supported file size: Up to 5 MB.
The scene and label parameters
When you submit a moderation task, you must specify the scenes parameter. The moderation result includes the label parameter, which corresponds to the scenes you specified.
| Scene | Description | imageScenes or textScenes | label |
| Detecting images within files | Detects specific information in the images within a file. | Pass the imageScenes parameter. Valid values:
| The label values for each scene are the same as those for image moderation. |
| Detecting text in files | Detects specific information in the text within a file. | Pass the textScenes parameter. Set the value to antispam | The label values for this scene are the same as those for text moderation. |
QPS limit
The queries per second (QPS) limit for this operation is 5 calls per second for each user. If you exceed this limit, API calls are throttled. This may affect your business. Plan your calls accordingly.
Request parameters
| Name | 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 moderation policies. |
| textScenes | StringArray | No | ["antispam"] | If the content to moderate includes text, specify the moderation scenario. Set the value to antispam. Note This parameter and imageScenes cannot both be empty. |
| imageScenes | StringArray | No | ["porn","ad"] | If the content to moderate includes images, specify the moderation scenario. Valid values include the following:
Note
|
| callback | String | No | http://www.aliyundoc.com/xx.json | 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 periodically. 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 successfully receives a callback notification, the server sends an HTTP 200 status code 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 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 | test | This value is used for the signature in the callback notification request. Note This field is required when you pass the callback parameter. |
cryptType | String | No | SHA256 | The encryption algorithm used to encrypt the callback notification content when you enable callback notification. AI Guardrails 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:
|
| tasks | JSONArray | Yes | Specifies the moderation objects. Each element in the JSON array is a moderation task object. You can submit up to 100 elements, which means you can moderate 100 pieces of content at a time. To submit 100 elements, you must set the number of concurrent tasks to 100 or more. For a detailed description of each element's structure, see task. |
| Name | Type | Required | Example | Description |
| clientInfo | JSONObject | No | {"userId":"28645****","userNick":"Mike","userType":"others"} | The information about the client. For more information, see the "Common request parameters" section of Common parameters. 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 | test2NInmO$tAON6qYUrtCRgLo-1mwxdi | The data ID. Ensure that all IDs are unique within a single request. |
| url | String | Yes | https://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.pdf | of the object to be detectedURL.
|
{
"code": 200,
"msg": "OK",
"dataId": "videoId xxx",
"taskId": "taskId xxx",
"results": [
{
"label": "porn",
"rate": 99.2,
"scene": "porn",
"suggestion": "block"
}
]
}Response data
| Name | Type | Example | Description |
| code | Integer | 200 | The returned HTTP status code. For more information, see Common error codes. |
| taskId | String | file_t_7Efx6ndTriK5Xx$rD2RFkr-1oB8zu | The ID of the moderation task. |
| dataId | String | testCvlKbUe4U@6uT6XJxh3G5-1oB8zu | The dataId from the corresponding request. |
| msg | String | OK | The response message for the request. |
Examples
http(s)://[Endpoint]/green/file/asyncscan
&<Common request parameters>
{
"bizType": "aligreen-test",
"textScenes": [
"antispam"
],
"imageScenes": [
"porn",
"ad"
],
"tasks": [
{
"dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
"url": "https://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.pdf"
},
{
"dataId": "test2NInmO$tAON6qYUrtCRgLo-aksdjak",
"url": "https://www.aliyundoc.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.pdf"
}
]
}{
"code": 200,
"data": [
{
"code": 280,
"dataId": "testCvlKbUe4U@6uT6XJxh3G5-1oB8zu",
"msg": "PROCESSING - queue",
"taskId": "file_t_7Efx6ndTriK5Xx$rD2RFkr-1oB8zu"
}
],
"msg": "OK",
"requestId": "B15C5A4F-9752-4F25-9DF8-9FF3446E72C9"
}