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:

This is a paid API operation. For more information about billing, see Content Moderation Pricing.
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 limit

The queries per second (QPS) limit for this API is 50 per user. Exceeding this limit triggers throttling, which can impact your business. Plan your calls accordingly.

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	The `callback` interface must support the POST method, UTF-8 encoded data, and the form parameters checksum and content. Content Moderation sets the checksum and content parameters according to the following rules and formats, and calls your `callback` interface to return the detection results. checksum: A SHA-256 hash of the concatenated string `User UID + seed + content`. The user UID is your Alibaba Cloud account ID, which is available in the Alibaba Cloud console. To prevent tampering, regenerate this string on your end and verify it against the received checksum. Note The user UID must be that of the root account, not a RAM user. content: A JSON string that you must parse. For an example of the content payload, see the sample response in "Query detection results". Note After your callback server receives a result notification, it must return an HTTP status code of 200 to indicate success. Any other status code is treated as a failure. If the notification fails, Content Moderation retries up to 16 times until it succeeds. If it still fails after 16 retries, no more attempts are made. We recommend that you check the status of your callback endpoint.
seed	String	Yes	seedxxx	A random string used for the signature in the callback notification request. The string can contain letters, digits, and underscores (_), and must be 64 characters or less. Customize this string to verify the origin of callback requests. Note This parameter is required when you use a callback.
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	The URL of the object to detect. A public HTTP or HTTPS URL. The URL cannot exceed 2,048 characters in length. The path of a file stored in an Alibaba Cloud OSS bucket. You must first grant Content Moderation permissions to access the OSS bucket. The OSS bucket must be in the same region as the Content Moderation service. For more information, see Authorize Content Moderation to access an OSS bucket. File path format: oss://<bucket-name>.<endpoint>/<object-name>
dataId	String	No	dataIdxxxx	The data ID of the detection object. This ID can contain uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.), and must be 128 characters or less. Use it to uniquely identify your business data.

Returned data (manual review)

Name	Type	Example	Description
code	Integer	200	The error code. It is the same as the 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 error code. It is the same as the HTTP status code. For more information, see Common error codes.
dataId	String	dataIdxxxx	The data ID of the detection object. Note If dataId was passed in the detection request, the same dataId 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	The URL of the object to detect. A public HTTP or HTTPS URL. The URL cannot exceed 2,048 characters in length. The path of a file stored in an Alibaba Cloud OSS bucket. You must first grant Content Moderation permissions to access the OSS bucket. The OSS bucket must be in the same region as the Content Moderation service. For more information, see Authorize Content Moderation to access an OSS bucket. 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 limit

The queries per second (QPS) limit for this API is 50 per user. Exceeding this limit triggers throttling, which can impact your business. Plan your calls accordingly.

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 error code. It is the same as the 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 error code. It is the same as the HTTP status code. For more information, see Common error codes.
dataId	String	dataIdxxxx	The data ID of the detection object. Note If dataId was passed in the detection request, the same dataId 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	The URL of the object to detect. A public HTTP or HTTPS URL. The URL cannot exceed 2,048 characters in length. The path of a file stored in an Alibaba Cloud OSS bucket. You must first grant Content Moderation permissions to access the OSS bucket. The OSS bucket must be in the same region as the Content Moderation service. For more information, see Authorize Content Moderation to access an OSS bucket. 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"
}