Submit synchronous face comparison tasks - Content Moderation

This topic provides specific interfaces and parameter descriptions for calling image synchronization detection tasks to perform face 1:1 comparison. It is designed to help you write programs to build HTTP call requests.

Description

Operation: /green/image/scan

Submit an image synchronization detection task to perform a 1:1 comparison between face photos and detect the similarity between two face photos. For more information about how to construct an HTTP request, see Request structure. You can also select an existing HTTP request. For more information, see SDK overview.

Billing:
You are charged for calling this operation. For more information about the billing methods, see
Note
For the face comparison feature, pass in two images for one comparison to be billed once (instead of twice).

checkTimeout:
The maximum response time that is allowed for a synchronous moderation request is 6s. If the moderation is not complete within 6s, a timeout error is returned. If you do not have high real-time requirements, you can select asynchronous detection. In other cases, select synchronous detection. It is relatively simple to call the synchronous detection interface. We recommend that you set the timeout period to 6s for calling synchronous moderation operations.

Limits on images:

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 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 the common request parameters that must be included in all Content Moderation API requests, see Common parameters.

The request body is a JSON object. The fields are described as follows:

Parameter	Type	Required	Example	Description
bizType	String	No	default	The business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize policies for machine-assisted moderation.
scenes	StringArray	Yes	["sface-1"]	The scenario in which the image is moderated. Valid values: sface-1.
tasks	JSONArray	Yes		The list of moderation objects. Each element in the JSON array is a moderation task structure. The JSON array can contain a maximum of 100 elements. In other words, you can submit a maximum of 100 images at a time. To submit 100 images at a time, you must raise the relevant concurrency limit to a number greater than 100. For more information about the structure of each element, see task.

Table 1. task

Parameter	Type	Required	Example	Description
dataId	String	No	e6b080a8-a91a-11e8-bac4-6c96cfde2af9	The ID of the image to be moderated. Make sure that each ID is unique in a request.
url	String	Yes	http://www.aliyundoc.com/2015/0826/2015082612403321.jpg	The HTTP or HTTPS URL that can be accessed over the Internet. The URL is up to 2,048 characters in length. Note Specifies the URL of the first image in the image to be compared.
extras	Map	No	xxx	Pass the second image in the image to be compared. The format is `{"faceUrl":"http://xxx.jpg"}`. where `faceUrl` is the URL of the second image.

Response parameters

For more information about common response parameters that are returned by this operation, see Common response parameters.

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

Parameter	Type	Example	Description
code	Integer	200	The returned HTTP status code. For more information, see Common error codes.
msg	String	OK	The message that is returned for the request.
dataId	String	e6b080a8-a91a-11e8-bac4-6c96cfde2af9	The ID of the moderated image, which you specify in the dataId parameter of the OCR request.
taskId	String	img2hsbmQeA4CU7l78$s8q5mW-1pnn7Z	The ID of the moderation task.
url	String	http://www.aliyundoc.com/2015/0826/2015082612403321.jpg	The HTTP or HTTPS URL that can be accessed over the Internet. The URL is up to 2,048 characters in length. Note The URL in the corresponding request, that is, the URL of the first image.
extras	Map	xxx	The extra parameters that were called. Note This parameter may be subject to changes. Use the latest value of this parameter.
results	JSONArray	No	The return results of the text moderation task. If HTTP status code 200 is returned after a successful call, the array in the return results contains one or more elements. Each element is a structure. For more information about the structure, see result.

Table 2. result

Parameter	Type	Example	Description
scene	String	sface-1	The risk scenario. Value: sface-1.
label	String	sface-1	The category of the detection result. Valid values: normal: The similarity between the second image and the first image is low. sface-1: second pictures with the first image similarity high.
suggestion	String	review	The machine-assisted moderation result of the moderated image. Valid values: pass: The image similarity is low and no other operations are required. review: The similarity. We recommend that you perform subsequent operations.
rate	Float	97.0	The result is the probability of the classification. Valid values: 0 to 100. A larger value indicates a higher probability that the audio falls into this category.

Examples

Sample requests

http(s)://[Endpoint]/green/image/scan
&<Common request parameters>

{
  "scenes":["sface-1"],
  "tasks":[
    {
      "url":"http://www.aliyundoc.com/2015/0826/2015082612403321.jpg",
      "dataId":"e6b080a8-a91a-11e8-bac4-6c96cfde2af9",
      "extras":{
          "faceUrl":"http://www.aliyundoc.com/c/u/2013/0313/1363136852136.jpg"
        }
    }
  ]
}

Sample success responses

{
    "code":200,
    "msg":"OK",
    "requestId":"9EEF894F-A933-4830-97B1-EC1A9630A9D6",
    "data":[
        {
            "code":200,
            "dataId":"e6b080a8-a91a-11e8-bac4-6c96cfde2af9",
            "taskId":"img2hsbmQeA4CU7l78$s8q5mW-1pnn7Z",
            "url":"http://www.aliyundoc.com/2015/0826/2015082612403321.jpg",
            "extras":{

            },
            "msg":"OK",
            "results":{
                "label":"sface-1",
                "rate":97,
                "scene":"sface-1",
                "suggestion":"review"
            }
        }
    ]
}