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

Note

Before you use this service, contact your account manager to confirm the audit standards and content scope. Calling this API does not return machine detection results. If you need machine detection results, call a detection service API. For more information about the detection service APIs, see Synchronous detection and Asynchronous detection.

Usage notes for manual image review

API operation: /green/image/manual/asyncScan

The manual review operation does not return detection results in real time. You can obtain the results through callbacks or by polling. The detection results are retained for a maximum of 30 days.

Billing information:

You are charged for calling this operation. For more information about the billing methods, see
Return results:
The time required to return the results of a manual review depends on the volume of data to be reviewed.
- Obtain review results using callbacks: When you submit manual review tasks, pass the callback parameter in the request to receive detection results automatically. For more information, see Request parameters (Manual review).
- Obtain review results by polling: When you submit manual review tasks, you do not need to pass the callback parameter. After you submit the tasks, call the result query operation to retrieve the detection results. For more information, see Usage notes for querying manual image review results.
Image requirements:
- Image URLs must use the HTTP or HTTPS protocol.
- Supported image formats: PNG, JPG, JPEG, BMP, GIF, and WEBP.
- The image size cannot exceed 20 MB for both synchronous and asynchronous invocations, the height or width cannot exceed 30,000 pixels, and the total number of pixels in the image cannot exceed 250 million.
- The image download timeout period is 3 seconds. If an image fails to download within 3 seconds, a timeout error is returned.
- Ensure that the storage service for the images to be detected is stable and reliable. We recommend that you use Alibaba Cloud Object Storage Service (OSS) or Alibaba Cloud CDN.

For more information about how to use this operation, see Use 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 (Manual review)

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

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

Name	Type	Required	Example value	Description
callback	String	No	http://www.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 detection task struct. You can specify up to 100 elements, which means you can submit 100 pieces of content for detection at a time. To support 100 elements, you must adjust the number of concurrent tasks to 100 or more. For more information about the structure of each element, see task.

Table 1. task
Name	Type	Required	Example value	Description
url	String	Yes	http://www.aliyundoc.com/xxx.jpg	of the object to be detectedURL. Public network HTTP/HTTPS URL, and the length cannot exceed2048 characters. Alibaba Cloud OSSthe file path provided.You must first authorize Content Moderation to accessOSSbucket, only in the same regionOSS bucket.For more information, seeauthorize Content Moderation to accessOSSbucket. file path format: oss://<bucket-name>.<endpoint>/<object-name>
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.

Returned data (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 response message.
requestId	String	147DE21C-6B0E-4331-87E9-77941376E109	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 response message for the detection task.
taskId	String	img6I5NQPVSQ7G4PsB79Z40iJ-1tyzUJ	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.
url	String	http://www.aliyundoc.com/xxx.jpg	of the object to be detectedURL. Public network HTTP/HTTPS URL, and the length cannot exceed2048 characters. Alibaba Cloud OSSthe file path provided.You must first authorize Content Moderation to accessOSSbucket, only in the same regionOSS bucket.For more information, seeauthorize Content Moderation to accessOSSbucket. file path format: oss://<bucket-name>.<endpoint>/<object-name>

Examples (Manual review)

Sample request

http(s)://[Endpoint]/green/image/manual/asyncScan
&<Common request parameters>
{
    "callback": "http://www.aliyundoc.com",
    "seed": "seedxxx",
    "tasks": [{
        "url": "http://www.aliyundoc.com/xxx.jpg",
        "dataId": "dataIdxxxx"
    }]
}

Sample success response

{
    "code": 200,
    "data": [{
        "code": 200,
        "dataId": "dataIdxxxx",
        "msg": "OK",
        "taskId": "img6I5NQPVSQ7G4PsB79Z40iJ-1tyzUJ",
        "url": "http://www.aliyundoc.com/xxx.jpg"
    }],
    "msg": "OK",
    "requestId": "147DE21C-6B0E-4331-87E9-77941376E109"
}

Usage notes for querying manual image review results

API operation: /green/image/manual/scan/results. You can use this operation to query the results of a manual image 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 (Result query)

Name	Type	Required	Sample value	Description
body	StringArray	Yes	["img6I5NQPVSQ7G4PsB79Z40iJ-1tyzUJ"]	A list of taskIds for the manual review tasks that you want to query. The array can contain a maximum of 100 elements.

Response parameters (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 response message.
requestId	String	1608A116-39C9-4080-A615-1E445DEF8841	The request ID.

Table 3. 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 response message for the detection task.
suggestion	String	block	The recommended subsequent operation. Valid values: pass: The result is normal. No further action is required. block: The result is a violation. We recommend that you delete the object or restrict its public access.
taskId	String	img6I5NQPVSQ7G4PsB79Z40iJ-1tyzUJ	The task ID.
url	String	http://www.aliyundoc.com/xxx.jpg	of the object to be detectedURL. Public network HTTP/HTTPS URL, and the length cannot exceed2048 characters. Alibaba Cloud OSSthe file path provided.You must first authorize Content Moderation to accessOSSbucket, only in the same regionOSS bucket.For more information, seeauthorize Content Moderation to accessOSSbucket. file path format: oss://<bucket-name>.<endpoint>/<object-name>

Examples (Result query)

Sample request

http(s)://[Endpoint]/green/image/manual/scan/results
&<Common request parameters>
[
    "img6I5NQPVSQ7G4PsB79Z40iJ-1tyzUJ"
]

Sample success response

{
    "code": 200,
    "data": [{
        "code": 200,
        "dataId": "dataIdxxxx",
        "msg": "OK",
        "suggestion": "block",
        "taskId": "img6I5NQPVSQ7G4PsB79Z40iJ-1tyzUJ",
        "url": "http://www.aliyundoc.com/xxx.jpg"
    }],
    "msg": "OK",
    "requestId": "1608A116-39C9-4080-A615-1E445DEF8841"
}