AI Guardrails:Image face retrieval

Key concepts

Operation description

Call imageScan to submit a synchronous image moderation task for Custom Face Retrieval. For details on constructing HTTP requests, see Request structure. Alternatively, use an SDK — see SDK overview.

Billing

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

Response 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. If you do not require moderation results in real time, you can send asynchronous moderation requests. In most cases, results are returned within 1 second. We recommend that you set the timeout period to 6 seconds for calling synchronous moderation operations. Response time may increase when the system is under heavy load, images are large, or images contain a large number of words.

Image requirements

• Image URL must use HTTP or HTTPS.

• Supported formats: PNG, JPG, JPEG, BMP, GIF, WEBP.

• Maximum image size: 20 MB (applies to both synchronous and asynchronous requests).

• Image download timeout: 3 seconds. If the image cannot be downloaded within 3 seconds, a timeout error is returned.

• Minimum recommended resolution: 256 × 256 pixels.

• Use a stable storage service such as Object Storage Service (OSS) or Content Delivery Network (CDN) to host images, to avoid download failures that affect response time.

QPS limits

50 calls per second per account. Exceeding this limit triggers throttling, which may affect your service.

Request syntax

POST /green/image/scan HTTPS|HTTP

Request headers

This operation uses only common request headers. For more information, see Common request headers.

Request parameters

Response elements

All responses return JSON. For common response parameters, see Common response parameters. The data field contains business-specific results.

The data field may be empty if an error occurs.

Table 2. result

Table 3. topPersonData

Table 4. person

Similarity score and false recognition rate

Table 5. faceItem

Examples

Sample request

POST /green/image/scan HTTP/1.1
Common request headers
{
    "scenes": [
        "sface-n"
    ],
    "tasks": [
        {
            "dataId": "test2NInmOtAON6qYUrtCRgLo-1mwxdi",
            "url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png",
            "extras": {
                "groupId": "group"
            }
        }
    ]
}

Sample success response

{
    "code": 200,
    "data": [
        {
            "code": 200,
            "dataId": "test2NInmOtAON6qYUrtCRgLo-1mwxdi",
            "msg": "The call is successful.",
            "results": [
                {
                    "topPersonData": [
                        {
                            "faceItem": {
                                "height": 422,
                                "width": 422,
                                "x": 467,
                                "y": 199
                            },
                            "persons": [
                                {
                                    "faceId": "14736649593638",
                                    "personId": "person1",
                                    "rate": "0.999"
                                },
                                {
                                    "faceId": "14736649593637",
                                    "personId": "person2",
                                    "rate": "0.998"
                                }
                            ]
                        }
                    ],
                    "label": "sface-n",
                    "rate": 0.999,
                    "scene": "sface-n",
                    "suggestion": "review"
                }
            ],
            "taskId": "img2MVcKPU1QGD64LoAb4cK6w-1mwxdi",
            "url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
        }
    ],
    "msg": "OK",
    "requestId": "36D384DA-8023-4E84-BCFD-0C5581352C16"
}