Submit asynchronous face comparison tasks - Content Moderation

This topic describes how to call the image asynchronous detection interface (/green/image/asyncscan) to perform a 1:1 comparison of face images. Face comparison helps you detect the similarity between two face photos.

Description about asynchronous image moderation

Operation: /green/image/asyncscan

You can call this operation to submit asynchronous image moderation tasks. 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 method:
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.
Response timeout:
The maximum response time that is allowed for a synchronous moderation request is 6 seconds. If the moderation is not completed within 6 seconds, a timeout error is returned. If you do not require moderation results in real time, you can send asynchronous moderation requests. In most cases, we recommend that you send synchronous moderation requests because synchronous moderation operations are easier to call. We recommend that you set the timeout period to 6 seconds for calling synchronous moderation operations.
Return results:
If you send asynchronous moderation requests, the moderation results are not returned in real time. To obtain moderation results, you can poll the moderation results periodically or enable callback notification. The moderation results are retained for up to 1 hour.
- callback to obtain detection results: When you submit an asynchronous detection task, you can specify callback parameters in the request parameters to automatically receive the detection results. For more information, see Request parameters.
- Polling to obtain detection results: When you submit an asynchronous detection task, you do not need to specify callback parameters. After you submit an asynchronous detection task, you can call the result query operation to obtain the detection results. For more information, see Description about /green/image/results.
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

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"]	Specifies the detection scenario. Valid value: sface-1, which indicates face comparison.
callback	String	No	http://www.aliyundoc.com/xx.json	The callback URL for notifying you of asynchronous moderation results. HTTP and HTTPS URLs are supported. If you do not set this parameter, you must poll moderation results periodically. 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	No	aabbcc123	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.
cryptType	String	No	SHA256	The encryption algorithm used to encrypt the callback notification content when you enable callback notification. Content Moderation encrypts the returned string by using the encryption algorithm that you specify and sends the encrypted string to the callback URL. The returned string is in the `UID + Seed + Content` format. Valid values: SHA256: The HMAC-SHA256 encryption algorithm is used. This is the default value. SM3: The HMAC-SM3 encryption algorithm is used, and a hexadecimal string is returned. The string consists of lowercase letters and digits. For example, 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 is returned after you encrypt abc by using the HMAC-SM3 encryption algorithm.
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 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.
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	JSONObject	No	{"faceUrl":"http://www.aliyundoc.com/c/u/2013/0313/1363136852136.jpg"}	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

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 moderation object. Note If you set the dataId parameter in the moderation request, the value of the dataId request parameter is returned here.
taskId	String	fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695	The ID of the OCR 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 of the moderation object. The URL in the corresponding request, that is, the URL of the first image.

Examples

Sample requests

http(s)://[Endpoint]/green/image/asyncscan
&<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"
            },
            "time": 949640
        }
    ]
}

Sample success responses

{
    "code": 200,
    "msg": "OK",
    "requestId": "95AD868A-F5D2-4AEA-96D4-E0273B8E074C",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "e6b080a8-a91a-11e8-bac4-6c96cfde2af9",
            "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
            "url": "http://www.aliyundoc.com/2015/0826/2015082612403321.jpg"
        }
    ]
}

Description about /green/image/results

Operation: /green/image/results

You can call this operation to query asynchronous image moderation results. 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 method:
This operation is free of charge.
Response timeout:
We recommend that you query moderation results at least 30 seconds after you send an asynchronous moderation request. Content Moderation retains moderation results for up to 4 hours. After 4 hours, the results are deleted.