Synchronous detection-阿里云帮助中心

This topic describes the API operations and parameters for submitting synchronous image detection tasks to perform liveness detection. You can use this information to build HTTP requests in your program.

Important Liveness and spoofing detection requires that an image contains a face. We recommend that you use this API operation with the sensitive face recognition feature. First, call the sensitive face recognition API operation to detect faces in an image. After a face is detected, call the liveness and spoofing detection API operation to determine whether the face is a spoof. For more information, see Sensitive face recognition.

Usage notes

API operation: /green/image/scan

Call this operation to submit a synchronous image detection task. The task performs liveness detection to determine whether a live object, such as a face, in an image is from a direct shot or a screen replay. To learn how to construct an HTTP request, see Request structure. You can also use a pre-constructed HTTP request. For more information, see SDK overview.

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

Detection time limit

The maximum detection time for a synchronous call is 6 seconds. If the detection does not complete within this time, the system returns a timeout error. If real-time results are not critical, use asynchronous detection. Otherwise, use synchronous detection, which is simpler to call. For synchronous calls, set the timeout period to 6 seconds.

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.
, The height or width cannot exceed30,000pixels (px), and the total pixels of the image cannot exceed2.5 hundred million (px)
Note
where, GIFformat images, the total pixels of the image cannot exceed4,194,304(px), The height or width cannot exceed30,000pixels (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 more information about the common request parameters that must be included in a request, see Common parameters.

The request body is a JSON object that contains the fields 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 Content Moderation console. For more information, see Customize policies for machine-assisted moderation.
scenes	StringArray	Yes	["liveness"]	The application scenario for image detection. The only valid value is liveness.
tasks	JSONArray	Yes		The detection objects. Each element in this JSON array is a detection task struct. You can specify up to 100 elements. To submit 100 elements at a time, you must set the number of concurrent tasks to more than 100. For more information about the structure of each element, see task.

Table 1. task
Name	Type	Required	Example	Description
dataId	String	No	test2NInmO$tAON6qYUrtCRgLo-1mwxdi	The data ID. Ensure that all IDs in a single request are unique.
url	String	Yes	https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png	The URL of the image to detect.

Returned data

For more information about the response, see Response parameters.

The `data` field in the response body is a JSON array. Each element in the array is an object that 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 response message for the request.
dataId	String	test2NInmO$tAON6qYUrtCRgLo-1mwxdi	Corresponds to the dataId in the request.
taskId	String	img2hsbmQeA4CU7l78$s8q5mW-1pnn7Z	The ID of the detection task.
url	String	https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png	Corresponds to the URL in the request.
extras	Map	xxx	Additional information. This value is subject to change. Do not create a business dependency on it.
results	JSONArray		The detection results. When the call is successful (code=200), the results contain one or more elements. Each element is a struct. For a description of the structure, see result.

Table 2. result
Name	Type	Example	Description
scene	String	liveness	The risk scenario. The only valid value is liveness.
label	String	liveness	The classification of the detection result. Valid values: normal: A live photo. liveness: A replayed photo.
suggestion	String	review	The recommended action. Valid values: pass: The object in the image is from a direct shot. No further action is needed. review: The object in the image may be from a screen replay. Confirm before you proceed. block: The object in the image is highly likely from a screen replay. Take further action.
rate	Float	97.0	The probability that the result belongs to this classification. The value ranges from 0.00 to 100.00. A higher value indicates a higher probability.
livenessData	JSONObject		The liveness detection information returned when the result is a replay (label=liveness). For a description of the structure, see livenessData.

Table 3. livenessData
Name	Type	Example	Description
rate	Float	97.0	The probability that the liveness photo is a recaptured photo. A higher score indicates a higher probability.

Examples

Request example

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

{
  "scenes": ["liveness"],
  "tasks": [
    {
      "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
      "url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
    }
  ]
}

Response example

{
 "code": 200,
 "msg": "OK",
 "requestId": "9EEF894F-A933-4830-97B1-EC1A9630A9D6",
 "data": [{
  "code": 200,
  "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
  "taskId": "img2hsbmQeA4CU7l78$s8q5mW-1pnn7Z",
  "url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png",
  "msg": "OK",
  "results": {
   "label": "liveness",
   "rate": 97.0,
   "scene": "liveness",
   "suggestion": "review",
   "livenessData": {
   "rate": 97.0
   }
  }
 }]
}