How to call the manual text review operation-AI Guardrails(AI Guardrails)-阿里云帮助中心

Note

Before you use this service, contact your account manager to determine the review standards and content scope. This operation does not return machine-based detection results. If you need machine-based detection results, you must call a detection service operation. For more information about detection service operations, see Synchronous text detection.

Usage notes for manual text review

Operation: /green/text/manual/asyncScan

The manual review operation does not return detection results in real time. You must obtain the results using a callback or polling. The detection results are retained for a maximum of 30 days.

Billing:

You are charged for calling this operation. For more information about the billing methods, see
Response:
The time it takes to return manual review results depends on the amount of data to be reviewed.
- Obtain detection results using a callback: When you submit manual review tasks, you can specify the callback parameter in the request to automatically receive the detection results. For more information, see Request parameters.
- Obtain detection results using polling: When you submit manual review tasks, you do not need to specify the callback parameter. After you submit the tasks, you can call the result query operation to obtain the detection results. For more information, see Usage notes for querying manual text review results.

For more information about how to use this operation, see Enable the manual review service.

QPS limits

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 for manual review

For more information about the common request parameters that must be included in requests, see Common parameters.

The request body is a JSON struct that contains the following fields:

Name	Type	Required	Example	Description
callback	String	No	http://aliyundoc.com	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: 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 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 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	Yes	seedxxx	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.
tasks	JSONArray	No		The detection objects. Each element in the JSON array is a struct for a detection task. You can specify up to 100 elements. This means you can submit up to 100 pieces of content for detection at a time. To specify 100 elements, you must set the number of concurrent tasks to more than 100. For more information about the structure of each element, see task.

Table 1. task
Name	Type	Required	Example	Description
content	String	Yes	test	The text content for manual review. The content can be up to 10,000 characters in length, including Chinese characters, letters, and punctuation marks.
dataId	String	No	dataIdxxxx	The ID of the moderation 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.

Response parameters for manual review

Name	Type	Example	Description
code	Integer	200	The returned HTTP status code. For more information, see Common error codes.
data	JSONArray		The data returned for the request. Each element in the array indicates the result of a manual review task. For more information about the structure of each element, see data.
msg	String	OK	The message returned for the request.
requestId	String	2C01A0EE-B5BF-429B-898A-9F6D301342EB	The request ID.

Table 2. data
Name	Type	Example	Description
code	Integer	200	The returned HTTP status code. For more information, see Common error codes.
dataId	String	dataIdxxxx	The ID of the moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here.
msg	String	OK	The message returned for the detection task.
taskId	String	txt17xfqjr4XWx4FrfsGw5YxL-1tyzBX	The ID of the manual review task. You can use this ID to call the result query operation to query the result of the manual review task.
content	String	text	The text content for manual review. The content can be up to 10,000 characters in length, including Chinese characters, letters, and punctuation marks.

Examples for manual review

Sample request

http(s)://[Endpoint]/green/text/manual/asyncScan
&<Common request parameters>
{
    "callback": "http://aliyundoc.com",
    "seed": "seedxxx",
    "tasks": [{
        "content": "test text",
        "dataId": "dataIdxxxx"
    }]
}

Sample success response

{
    "code": 200,
    "data": [{
        "code": 200,
        "content": "test text",
        "dataId": "dataIdxxxx",
        "msg": "OK",
        "taskId": "txt17xfqjr4XWx4FrfsGw5YxL-1tyzBX"
    }],
    "msg": "OK",
    "requestId": "2C01A0EE-B5BF-429B-898A-9F6D301342EB"
}

Usage notes for querying manual text review results

Operation: /green/text/manual/scan/results. You can use this operation to query the results of a manual text review.

QPS limits

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 for result query

Name	Type	Required	Example value	Description
body	StringArray	Yes	["txt17xfqjr4XWx4FrfsGw5YxL-1tyzBX"]	A list of the taskId values of the manual review tasks that you want to query. The array can contain up to 100 elements.

Response parameters for result query

Name	Type	Example	Description
code	Integer	200	The returned HTTP status code. For more information, see Common error codes.
data	JSONArray		The data returned for the request. Each element in the array indicates the result of a manual review task. For more information about the structure of each element, see data.
msg	String	OK	The message returned for the request.
requestId	String	2061F868-396C-4F00-9F32-792914428EA1	The request ID.

Table 3. data
Name	Type	Example value	Description
code	Integer	200	The returned HTTP status code. For more information, see Common error codes.
dataId	String	dataIdxxxx	The ID of the moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here.
msg	String	OK	The message returned for the detection task.
suggestion	String	block	The recommended subsequent operation. Valid values: pass: The result is normal. No other operations are required. block: The result is a violation. We recommend that you delete the content or restrict public access to it.
taskId	String	txt17xfqjr4XWx4FrfsGw5YxL-1tyzBX	The task ID.
content	String	test text xxx	The text content for manual review.

Examples for result query

Sample request

http(s)://[Endpoint]/green/text/manual/scan/results
&<Common request parameters>
[
    "txt17xfqjr4XWx4FrfsGw5YxL-1tyzBX"
]

Sample success response

{
    "code": 200,
    "data": [{
        "code": 200,
        "content": "test text xxx",
        "dataId": "dataIdxxxx",
        "msg": "OK",
        "suggestion": "block",
        "taskId": "txt17xfqjr4XWx4FrfsGw5YxL-1tyzBX"
    }],
    "msg": "OK",
    "requestId": "2061F868-396C-4F00-9F32-792914428EA1"
}