Image search-AI Guardrails(AI Guardrails)-阿里云帮助中心

Call this operation to check for similarities between a specified image and images in a sample library.

Usage notes

API operation: /green/image/scan

The images to be moderated must meet the following requirements:

The URLs of images must be HTTP or HTTPS URLs.
The images must be in 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 height or width cannot exceed30,000pixels (px), and the total pixels of the image cannot exceed2.5 hundred million (px)
Note
where, GIFformat images, the total pixels of the image cannot exceed4,194,304(px), The height or width cannot exceed30,000pixels (px).
The duration for downloading an image is limited to 3 seconds. If an image fails to be downloaded within 3 seconds, a timeout error is returned.
We recommend that you submit images of at least 256 × 256 pixels to ensure the moderation effect.
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).

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 more information about common request parameters, see Common parameters.

The request body is a JSON object. The following table describes the fields in the object.

Name	Type	Required	Example	Description
scenes	String	Yes	similarity	For the similar image search feature, set this parameter to similarity.
tasks	JSONArray	Yes		The detection tasks. Each element in this JSON array is a task struct. You can submit up to 100 items for detection in a single request. To submit 100 items, 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
dataId	String	No	test6HPBmBm8AM46zcu30bRNq0-1p8xDK	The unique ID of the image to be detected in your business system.
url	String	Yes	http://example.com/testb.jpg	The URL of the image to be detected.
similarityLibraries	StringArray	No	["xxx"]	The names of the similar image libraries to search. If you do not specify this parameter, the system searches the default library. The name of the default library is default.

Response data

For more information about the response parameters, see Response results.

The `data` field in the response body is a JSON array. Each element contains the following fields:

Name	Type	Example	Description
code	Integer	200	The returned HTTP status code. For more information, see Common error codes.
msg	String	OK	The response message for the request.
results	JSONArray		The results. If the call is successful (`code=200`), this field contains one or more elements. Each element is a struct. For more information about the structure, see result.

Table 2. result
Name	Type	Example	Description
scene	String	similarity	The detection scenario. The value is similarity.
label	String	normal	The classification of the detection result. This corresponds to the `scene` in the request. For the similar image search feature, this parameter can be: normal: No similar image is hit. similarity: A similar image is hit.
suggestion	String	review	The recommended user action. The value can be: pass: No similar image is hit. review: A similar image is hit.
rate	Float	99.9	The highest similarity score among all hit sample images. The value ranges from 0.00 to 100.00. A higher value indicates a higher probability of a hit.
similarityImage	JSONArray		The results for hit similar images. This returns records with high similarity scores after comparing the detected image with all images in the sample library. For more information about the structure of each record, see similarityImageData.

Table 3. similarityImageData
Name	Type	Example	Description
dataId	String	test6HPBmBm8AM46zcu30bRNq0-1p8xDK	The unique ID of the hit sample image in your business system.
url	String	http://example.com/testb.jpg	The URL of the hit sample image.
tags	JSONArray	["pornography"]	The tags of the hit sample image.
rate	Float	99.9	The similarity score between the detected image and the hit sample image. The value ranges from 0.00 to 100.00. A higher value indicates a higher probability of a hit on this sample image.
library	String	xxx	The name of the library where the sample image is located.

Examples

Request example

http(s)://[Endpoint]/green/image/scan
&<Common request parameters>
{
  "scenes":["similarity"],
  "tasks":[
    {
      "url":"http://example.com/test.jpg",
      "similarityLibraries":["xxx"]
    }
  ]
}

Response example

{
  "requestId":"7B932A87-65EB-423A-A4BF-BDA65E29FCEE",
  "code":200,
  "msg":"OK",
  "data":[
    {
      "code":200,
      "msg":"OK",
      "results":[
        {
          "label":"normal",
          "rate":99.9,
          "scene":"similarity",
          "suggestion":"review",
          "similarityImageData":[
            {
              "url": "http://example.com/testb.jpg",
              "dataId": "test6HPBmBm8AM46zcu30bRNq0-1p8xDK",
              "rate": 99.9,
              "tags":["pornography"],
              "library":"xxx"
            }
          ]
        }
      ],
      "taskId":"img3IpdHbwwbv05pvXD8ud7F0-1p8xDC",
      "url":"http://example.com/test.jpg"
    }
  ]
}