Synchronous detection-阿里云帮助中心

This topic describes the API and parameters for synchronous image detection. You can use this information to build HTTP requests to detect tags in images.

Usage notes

API operation: /green/image/scan

You can submit a synchronous image detection task to detect and return the main tags in an image. The top N tags are returned in descending order of confidence level. For more information about how to construct an HTTP request, see Request structure. You can also use a pre-built HTTP request. For more information, see SDK overview.

You are charged for calling this operation. For more information about the billing methods, see

Detection duration

The maximum detection time for a synchronous task is 6 seconds. If a task exceeds this limit, the system returns a timeout error. If you do not require real-time results, you can use asynchronous detection. Otherwise, you can use synchronous detection, which is simpler to call. You should set the timeout period to 6 seconds for synchronous detection calls.

Image limits

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.
，高度或者宽度不能超过30,000像素（px），且图像总像素不超过2.5亿（px）
Note
其中，GIF格式的图片，图像总像素不超过4,194,304（px），高度或者宽度不能超过30,000像素（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 information about the common request parameters that must be included in a request, see Common parameters.

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

Name	Type	Required	Example	Description
bizType	String	No	default	The business scenario. You can create a business scenario in the 内容安全控制台. For more information, see Customize policies for machine-assisted moderation.
scenes	StringArray	Yes	["tag"]	The detection scenario. Set the value to tag.
tasks	JSONArray	Yes		The detection tasks. Each element in the JSON array is a task struct. You can submit up to 100 tasks at a time. To submit 100 tasks, you must set 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	Description
dataId	String	No	test35T5XhMsXfV4xKwUv8Ob74-1poXxF	The data ID. Make sure that all data IDs are unique in a request.
url	String	Yes	http://www.aliyundoc.com/2015/0826/2015082612403321.jpg	The URL of the image to detect.

Return data

For more information about the response, see Return 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 message returned for the request.
dataId	String	test35T5XhMsXfV4xKwUv8Ob74-1poXxF	The dataId from the request.
taskId	String	vi636L2Z$Q43i6LRrWdITWhq-1poXxF	The ID of the detection task.
url	String	http://www.aliyundoc.com/2015/0826/2015082612403321.jpg	The URL from the request.
extras	Map	xxx	Additional parameters. Note This parameter is subject to change. Do not rely on its return value.
results	Array		The detection results. If the call is successful (`code=200`), this array contains one or more `result` objects. For more information about the structure, see result.

Table 2. result
Name	Type	Example	Description
scene	String	tag	The image detection scenario. The value is tag.
label	String	tag	The classification of the detection result. Valid values: normal: The image is normal and has no tags. tag: The image contains tags.
suggestion	String	review	The recommended action. Valid values: pass: The image does not contain tags. No further action is required. review: The image contains tags. Further action is recommended.
rate	Float	99.91	The confidence level of the classification. The value ranges from 0.00 to 100.00. A higher value indicates a higher probability.
tagData	Object		The tag data that is returned when tags are detected (`label=tag`). For more information about the structure, see tagData.

Table 3. tagData
Name	Type	Example	Description
summary	Array		A summary of the tag information. For more information about the structure, see summary.

Table 4. summary
Name	Type	Example	Description
tgCnName	String	Aircraft	The name of the tag in Chinese.
tgEnName	String	Aircraft	The name of the tag in English.
cnCategory	String	xxx	The name of the tag category in Chinese.
enCategory	String	xxx	The name of the tag category in English.
rate	Float	99.91	The confidence level that the object is the specified tag. The value ranges from 0 to 100. A higher value indicates a higher probability.

Examples

Request example

http(s)://[Endpoint]/green/image/scan
&<Common request parameters>
{
  "scenes": ["tag"],
  "tasks": [
    {
      "dataId": "test35T5XhMsXfV4xKwUv8Ob74-1poXxF",
      "url": "http://www.aliyundoc.com/2015/0826/2015082612403321.jpg"
    }
  ]
}

Response example

{
  "msg": "OK",
  "code": 200,
  "data": [
    {
      "msg": "OK",
      "code": 200,
      "dataId": "test35T5XhMsXfV4xKwUv8Ob74-1poXxF",
      "results": [
        {
          "tagData": {
            "summary": [
              {
                "rate": 37.72,
                "tagEnName": "Aircraft",
                "tagCnName": "Aircraft"
              },
              {
                "rate": 31.93,
                "tagEnName": "Hotel",
                "tagCnName": "Hotel"
              }
            ]
          },
          "rate": 99.91,
          "suggestion": "review",
          "label": "tag",
          "scene": "tag"
        }
      ],
      "taskId": "vi636L2Z$Q43i6LRrWdITWhq-1poXxF",
      "url": "http://www.aliyundoc.com/2015/0826/2015082612403321.jpg"
    }
  ],
  "requestId": "5CAED310-CC31-4E34-9EB5-3C2E741BB870"
}