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

Compares two face images and returns a similarity score, indicating whether the faces belong to the same person.

Operation: /green/image/scan

For request construction details, see Request structure. To use an SDK instead of raw HTTP, see SDK overview.

Billing

Passing two images for a single face comparison is billed once, not twice.

For pricing details, see the Content Moderation pricing page.

Limits

QPS limit

50 calls per second per account. Calls that exceed this limit are throttled.

Timeout

The maximum response time for a synchronous moderation request is 6 seconds. If moderation does not complete within 6 seconds, a timeout error is returned. For workloads without strict real-time requirements, use asynchronous moderation instead. Set your client timeout to 6 seconds when calling this operation.

Image requirements

Requirement	Limit
URL scheme	HTTP or HTTPS
Formats	PNG, JPG, JPEG, BMP, GIF, WEBP
Max file size	20 MB
Download timeout	3 seconds
Recommended minimum resolution	256 x 256 pixels

If an image fails to download within 3 seconds, a timeout error is returned. For reliable download performance, store images in Object Storage Service (OSS) or a Content Delivery Network (CDN).

Request parameters

For common request parameters required by all Content Moderation API requests, see Common parameters.

The request body is a JSON object with the following fields:

Parameter	Type	Required	Example	Description
`bizType`	String	No	`default`	The business scenario. Create and manage business scenarios in the Content Moderation console. See Customize policies for machine-assisted moderation.
`scenes`	StringArray	Yes	`["sface-1"]`	The moderation scenario. Valid value: `sface-1`.
`tasks`	JSONArray	Yes	—	The list of moderation objects. Each element is a task object (see below). Maximum 100 elements per request. To submit 100 tasks in a single request, raise the concurrency limit to more than 100.

task object

Parameter	Type	Required	Example	Description
`dataId`	String	No	`e6b080a8-a91a-11e8-bac4-6c96cfde2af9`	A unique identifier for the task within the request.
`url`	String	Yes	`http://www.aliyundoc.com/2015/0826/2015082612403321.jpg`	The URL of the first image to compare. Must be an HTTP or HTTPS URL accessible over the internet. Maximum 2,048 characters.
`extras`	Map	No	`{"faceUrl":"http://xxx.jpg"}`	The second image to compare, passed as `{"faceUrl": "<second-image-url>"}`.

The two images use different parameters: the first image goes in url, and the second goes in extras.faceUrl. Both must be publicly accessible HTTP or HTTPS URLs.

Response parameters

For common response fields, see Common response parameters.

The data field is a JSON array. Each element contains:

Parameter	Type	Example	Description
`code`	Integer	`200`	The HTTP status code. See Common error codes.
`msg`	String	`OK`	The status message for the request.
`dataId`	String	`e6b080a8-a91a-11e8-bac4-6c96cfde2af9`	The `dataId` value from the corresponding request.
`taskId`	String	`img2hsbmQeA4CU7l78$s8q5mW-1pnn7Z`	The moderation task ID.
`url`	String	`http://www.aliyundoc.com/2015/0826/2015082612403321.jpg`	The URL of the first image from the request.
`extras`	Map	—	The extra parameters from the request. This field may change; always use the latest value.
`results`	JSONArray	—	The moderation results. Contains one or more result objects when `code` is `200`.

result object

Parameter	Type	Example	Description
`scene`	String	`sface-1`	The moderation scenario. Value: `sface-1`.
`label`	String	`sface-1`	The comparison result category. Valid values: `normal` (low similarity) or `sface-1` (high similarity).
`suggestion`	String	`review`	The recommended action. Valid values: `pass` (low similarity, no further action needed) or `review` (high similarity, manual review recommended).
`rate`	Float	`97.0`	The face similarity score. Range: 0–100. A higher value indicates greater similarity.

Examples

Request

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

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

Response

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

In this example, suggestion: review and rate: 97 indicate that the two face images have high similarity and likely belong to the same person.