Calling the Face Attribute Detection API-AI Guardrails(AI Guardrails)-阿里云帮助中心

Usage

API endpoint: /green/face/detect. This API performs synchronous detection of face attributes.

You can call this API to create a face attribute detection task and immediately receive the detection results. For information about how to construct an HTTP request, see Request structure. You can also use a pre-built SDK request. For more information, see SDK overview.

Billing

This is a paid API operation. For more information about billing, see Content Moderation Pricing.
Detection timeout

The maximum detection time for a synchronous detection request is 6 seconds. If the detection is not completed within this time limit, a timeout error is returned. If you do not require real-time results, you can use asynchronous detection. Otherwise, use synchronous detection because its API call is simpler. For these calls, set the timeout period to 6 seconds.
Return Results

Synchronous detection requests typically return a result within one second. However, the response time may increase in specific scenarios, such as high system load, large image size, or a large amount of text for optical character recognition (OCR).
Image requirements
- The image URL must use the HTTP or HTTPS protocol.
- Supported image formats: PNG, JPG, JPEG, BMP, GIF, and WEBP.
- The image size cannot exceed 20 MB for both synchronous and asynchronous calls. The height or width cannot exceed 30,000 pixels (px), and the total number of pixels cannot exceed 250 million (px).
  Note
  For GIF images, the total number of pixels cannot exceed 4,194,304 (px), and the height or width cannot exceed 30,000 pixels (px).
- The image must be downloaded within 3 seconds. If the download time exceeds 3 seconds, a download timeout error is returned.
- For optimal performance, we recommend that the image resolution be at least 256x256 pixels. A lower resolution may affect the detection accuracy.
- The response time of the image detection API depends on the image download time. Ensure that the storage service where the image is stored is stable and reliable. For best performance, use Alibaba Cloud Object Storage Service (OSS) or a Content Delivery Network (CDN).

QPS limit

The queries per second (QPS) limit for this API is 50 per user. Exceeding this limit triggers throttling, which can impact your business. Plan your calls accordingly.

Request parameters

Parameter	Type	Required	Description
bizType	String	No	This field identifies your business scenario. You can create a business scenario in the Content Moderation console. For more information, see Customize moderation rules.
dataId	String	No	The ID of the image to be detected. If you specify this parameter, its value is returned in the response. You can use this ID to associate the response with a specific image.
url	String	Yes	The URL of the image to be detected.

Response parameters

Parameter	Type	Description
code	String	The status code for the request. A value of `200` indicates success.
msg	String	The response message.
dataId	String	The data ID of the detection object. Note If dataId was passed in the detection request, the same dataId is returned here.
taskId	String	The ID of the detection task.
url	String	The URL of the object to detect. A public HTTP or HTTPS URL. The URL cannot exceed 2,048 characters in length. The path of a file stored in an Alibaba Cloud OSS bucket. You must first grant Content Moderation permissions to access the OSS bucket. The OSS bucket must be in the same region as the Content Moderation service. For more information, see Authorize Content Moderation to access an OSS bucket. File path format: oss://<bucket-name>.<endpoint>/<object-name>
faces	JSONArray	If the call is successful (`code` is 200), this parameter contains the face attribute detection results. Each element in the array corresponds to one detected face. For the structure of each element, see face.

Table 1. face
Parameter	Type	Description
location	JSONObject	The location of the face. For details about the structure, see location.
smile	JSONObject	The smile level of the face. For details about the structure, see smile.
glasses	JSONObject	Indicates whether the person is wearing glasses. For details about the structure, see glasses.
quality	JSONObject	Information about the quality of the face image. For details about the structure, see quality.
qualified	Boolean	Indicates whether the quality of the face image is acceptable. Valid values: true: The quality is acceptable. false: The quality is not acceptable. For each face detected in the image, Content Moderation assesses whether the image quality is acceptable. An acceptable face image must meet all the following criteria: The face blurriness is less than 5. The person is not wearing sunglasses. The face pose angles (pitch, yaw, and roll) are within ±30 degrees. You can use the returned face attribute values to control image quality, for example, when managing a face database.
respirator	JSONObject	Indicates whether the person is wearing a mask. For details about the structure, see respirator.
hat	JSONObject	Indicates whether the person is wearing a hat. For details about the structure, see hat.
mustache	JSONObject	Indicates whether the person has a mustache. For details about the structure, see mustache.
help	JSONObject	Indicates whether the person has bangs. For details about the structure, see bang.
hairstyle	JSONObject	The detected hairstyle. For details about the structure, see hairstyle.

Table 2. location
Parameter	Type	Description
x	Float	The x-coordinate of the upper-left corner of the face's bounding box, relative to the image's upper-left corner. Unit: pixels.
y	Float	The y-coordinate of the upper-left corner of the face's bounding box, relative to the image's upper-left corner. Unit: pixels.
w	Float	The width of the face's bounding box. Unit: pixels.
h	Float	The height of the face's bounding box. Unit: pixels.

Table 3. smile
Parameter	Type	Description
value	Float	The smile level of the face. The value ranges from 0 to 1. A higher score indicates a more prominent smile.
rate	Float	The confidence level of the detection, from 0 to 1. A higher value indicates greater confidence.

Table 4. glasses
Parameter	Type	Description
value	String	Indicates whether the person is wearing glasses. Valid values: None: Not wearing glasses. Wear: Wearing regular glasses. Sunglass: Wearing sunglasses.
rate	Float	The confidence level of the detection, from 0 to 1. A higher value indicates greater confidence.

Table 5. quality
Parameter	Type	Description
blur	Float	The blurriness of the face image. The value ranges from 0 to 20. A higher score indicates a more blurry image. Recommended range: 0 to 5.
pitch	Float	The pitch angle of the face (nodding up or down). Recommended range: -30 to 30.
yaw	Float	The yaw angle of the face (turning head left or right). Recommended range: -30 to 30.
roll	Float	The roll angle of the face (tilting head side to side). Recommended range: -30 to 30.

Table 6. respirator
Parameter	Type	Description
value	String	Indicates whether the person is wearing a mask. Valid values: Wear: Wearing a mask. None: Not wearing a mask.
rate	Float	The confidence level of the detection, from 0 to 1. A higher value indicates greater confidence.

Table 7. hat
Parameter	Type	Description
value	String	Indicates whether the person is wearing a hat. Valid values: Wear: Wearing a hat. None: Not wearing a hat.
rate	Float	The confidence level of the detection, from 0 to 1. A higher value indicates greater confidence.

Table 8. mustache
Parameter	Type	Description
value	String	Indicates whether the person has a mustache. Valid values: Has: Has a mustache. None: Does not have a mustache.
rate	Float	The confidence level of the detection, from 0 to 1. A higher value indicates greater confidence.

Table 9. bang
Parameter	Type	Description
value	String	Indicates whether the person has bangs. Valid values: Has: Has bangs. None: Does not have bangs.
rate	Float	The confidence level of the detection, from 0 to 1. A higher value indicates greater confidence.

Table 10. hairstyle
Parameter	Type	Description
value	String	The detected hairstyle. Valid values: Bald: Bald. Long: Long hair. Short: Short hair.
rate	Float	The confidence level of the detection, from 0 to 1. A higher value indicates greater confidence.

Examples

Sample request

http(s)://[Endpoint]/green/face/detect
&<common request parameters>
{
    "bizType": "abc",
    "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
    "url": "http://example.com/face1.jpeg"
}

Sample response

{
    "msg": "OK",
    "code": 200,
    "extras": {
        "width": "328",
        "height": "390"
    },
    "faces": [
        {
            "glasses": {
                "rate": 0.99,
                "value": "None"
            },
            "qualified": false,
            "bang": {
                "rate": 0.99,
                "value": "Has"
            },
            "respirator": {
                "rate": 0.99,
                "value": "None"
            },
            "hat": {
                "rate": 0.99,
                "value": "None"
            },
            "location": {
                "w": 116,
                "h": 116,
                "x": 134,
                "y": 135
            },
            "mustache": {
                "rate": 0.99,
                "value": "None"
            },
            "hairstyle": {
                "rate": 0.99,
                "value": "Short"
            },
            "quality": {
                "roll": 0.38,
                "blur": 6.44,
                "pitch": 21.21,
                "yaw": 21.12
            },
            "smile": {
                "rate": 0.99,
                "value": 0.5
            }
        }
    ],
    "dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
    "taskId": "img1uJtIrlwH$F4FA3h$Sxe2F-1tbWWx",
    "url": "http://example.com/face1.jpeg"
}