Submit asynchronous face comparison tasks-AI Guardrails(AI Guardrails)-阿里云帮助中心

Submits a 1:1 face comparison task to /green/image/asyncscan and retrieves results from /green/image/results. Face comparison detects the similarity between two face images and returns a similarity score with a moderation suggestion.

Operation 1: Submit a face comparison task

Endpoint: POST /green/image/asyncscan

Submits asynchronous image moderation tasks for face comparison. To construct an HTTP request, see Request structure. Alternatively, use an existing SDK — see SDK overview.

Billing

Each face comparison counts as one billable call, regardless of the number of images passed in. Passing two images for a single comparison is billed once.

How it works

Submit a task with two image URLs — one in url and one in extras.faceUrl. Content Moderation processes the comparison asynchronously and holds results for up to 1 hour.

To retrieve results, either:

Callback (push): Specify the callback parameter in the request. Content Moderation pushes results to your endpoint automatically.
Polling: Omit callback. After submission, call /green/image/results to poll for results. Wait at least 30 seconds before your first poll.

Usage notes

Image requirements:

URLs must use HTTP or HTTPS.
Supported formats: PNG, JPG, JPEG, BMP, GIF, WEBP.
Maximum file size: 20 MB.
Download timeout: 3 seconds. Images that fail to download within 3 seconds return a timeout error.
Minimum recommended resolution: 256 × 256 pixels.
Store images on a reliable service such as Object Storage Service (OSS) or a Content Delivery Network (CDN) to avoid download failures.

Asynchronous behavior:

Results are not returned in the submission response. Use callback or polling to retrieve them.
Results are retained for up to 1 hour.

Response timeout for synchronous requests:

The maximum response time for a synchronous moderation request is 6 seconds. If moderation is not completed within 6 seconds, a timeout error is returned. We recommend setting the timeout period to 6 seconds when calling synchronous moderation operations.

QPS limit

50 calls per second per account. Exceeding this limit triggers throttling.

Request parameters

Parameter	Type	Required	Example	Description
`bizType`	String	No	`default`	The business scenario. Create and manage scenarios in the Content Moderation console. For details, see Customize policies for machine-assisted moderation.
`scenes`	StringArray	Yes	`["sface-1"]`	The detection scenario. Valid value: `sface-1` (face comparison).
`callback`	String	No	`http://www.aliyundoc.com/xx.json`	The callback URL for receiving asynchronous moderation results. Supports HTTP and HTTPS. If omitted, poll `/green/image/results` for results. The callback endpoint must support POST requests, UTF-8 encoding, and the `checksum` and `content` parameters. See Callback details below.
`seed`	String	No	`aabbcc123`	A random string used to generate the callback request signature. Maximum 64 characters; letters, digits, and underscores only. Required when `callback` is set.
`cryptType`	String	No	`SHA256`	The encryption algorithm for callback notifications. Valid values: `SHA256` (HMAC-SHA256, default), `SM3` (HMAC-SM3, returns a lowercase hexadecimal string).
`tasks`	JSONArray	Yes	—	The list of moderation tasks. Maximum 100 elements per request. To submit 100 images at a time, you must raise the relevant concurrency limit to a number greater than 100. Each element follows the `task` structure below.

task structure:

Parameter	Type	Required	Example	Description
`dataId`	String	No	`e6b080a8-a91a-11e8-bac4-6c96cfde2af9`	A unique identifier for the moderation object in your system. Maximum 128 characters; letters, digits, hyphens (`-`), underscores (`_`), and periods (`.`). Echoed in the response.
`url`	String	Yes	`http://www.aliyundoc.com/2015/0826/2015082612403321.jpg`	The URL of the first image. Must be publicly accessible via HTTP or HTTPS. Maximum 2,048 characters.
`extras`	JSONObject	No	`{"faceUrl":"http://www.aliyundoc.com/c/u/2013/0313/1363136852136.jpg"}`	The second image for comparison. Format: `{"faceUrl":"<image-url>"}`.

Callback details

When Content Moderation pushes a callback notification, it includes two parameters:

`checksum`: A signature string generated as SHA-256(UID + Seed + Content). UID is your Alibaba Cloud account ID (not a RAM user ID), which you can find in the Alibaba Cloud Management Console. Verify this signature on your server to detect tampering.
`content`: A JSON-encoded string containing the moderation result. The format matches the response from /green/image/results.

If your server returns HTTP 200, Content Moderation considers the notification delivered. If your server returns any other status, Content Moderation retries delivery up to 16 times. After 16 failed attempts, delivery stops — check your callback endpoint if this occurs.

When cryptType is SM3, Content Moderation uses HMAC-SM3 and returns a lowercase hexadecimal string. For example, encrypting abc produces 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0.

Response parameters

Parameter	Type	Example	Description
`code`	Integer	`200`	The HTTP status code. For a full list, see Common error codes.
`msg`	String	`OK`	The status message.
`dataId`	String	`e6b080a8-a91a-11e8-bac4-6c96cfde2af9`	The moderation object ID. Echoes the `dataId` from the request, if set.
`taskId`	String	`fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695`	The task ID. Use this ID to query results from `/green/image/results`.
`url`	String	`http://www.aliyundoc.com/2015/0826/2015082612403321.jpg`	The URL of the first image, echoed from the request.

Examples

Request:

POST 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
        }
    ]
}

Response:

{
    "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"
        }
    ]
}

Operation 2: Query face comparison results

Endpoint: POST /green/image/results

Queries the results of asynchronous face comparison tasks submitted via /green/image/asyncscan. To construct an HTTP request, see Request structure. Alternatively, use an existing SDK — see SDK overview.