Detects facial attributes in an image, including face blur, face angle, face position, smile intensity, hairstyle, and the presence of glasses, a mask, a hat, a beard, or bangs.
Usage notes
Endpoint: POST /green/face/detect
This operation submits a synchronous face attribute detection task and returns results immediately. For details on constructing HTTP requests, see Request structure. To use a pre-built HTTP client, see SDK overview.
Billing: Calls to this operation are billed. For pricing details, see the Content Moderation billing documentation.
Timeout: The maximum response time is 6 seconds. If detection does not complete within 6 seconds, a timeout error is returned. Set your client timeout to 6 seconds when calling this operation. If you do not require moderation results in real time, you can send asynchronous moderation requests. Results are typically returned within 1 second; response times may increase when the system is under heavy load, images are large, or images contain many text elements.
Image requirements:
URL must be HTTP or HTTPS, and publicly accessible.
Maximum URL length: 2,048 characters.
Supported formats: PNG, JPG, JPEG, BMP, GIF, WEBP.
Maximum file size: 20 MB.
Image download must complete within 3 seconds; a timeout error is returned if it does not.
Minimum recommended resolution: 256 × 256 pixels.
Store images in a stable, reliable service such as Object Storage Service (OSS) or Content Delivery Network (CDN) to avoid download failures.
QPS limits
50 calls per second per account. Exceeding this limit triggers throttling.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
| bizType | String | No | The business scenario. Create and manage business scenarios in the Content Moderation console. For details, see Customize policies for machine-assisted moderation. |
| dataId | String | No | A caller-defined ID for the image. If specified, this value is echoed back in the response and can be used to correlate requests with results. |
| url | String | Yes | The HTTP or HTTPS URL of the image to analyze. Maximum length: 2,048 characters. |
Response elements
| Name | Type | Description |
|---|---|---|
| code | String | The error code. This is the same as the HTTP status code. |
| msg | String | The error message. |
| dataId | String | The data ID specified in the request, if any. |
| taskId | String | The ID of the detection task. |
| url | String | The URL of the analyzed image. |
| faces | JSONArray | The detected faces. Each element represents one face. Returned only when code is 200. For details, see face. |
face
| Name | Type | Description |
|---|---|---|
| location | JSONObject | The bounding box of the face. For details, see location. |
| smile | JSONObject | The smile detection result. For details, see smile. |
| glasses | JSONObject | The glasses detection result. For details, see glasses. |
| quality | JSONObject | The quality metrics of the face image. For details, see quality. |
| qualified | Boolean | Whether the face image meets quality requirements. true means acceptable; false means not acceptable. A face is considered acceptable when all three conditions are met: blur value is less than 5, no sunglasses are worn, and pitch, yaw, and roll angles are all within 30 degrees. Use this field to filter faces for scenarios such as building a face database. |
| respirator | JSONObject | The mask detection result. For details, see respirator. |
| hat | JSONObject | The hat detection result. For details, see hat. |
| mustache | JSONObject | The mustache detection result. For details, see mustache. |
| bang | JSONObject | The bangs detection result. For details, see bang. |
| hairstyle | JSONObject | The hairstyle detection result. For details, see hairstyle. |
location
| Name | Type | Description |
|---|---|---|
| x | Float | The distance from the upper-left corner of the face area to the y-axis. The origin (0,0) is the upper-left corner of the image. Unit: pixel. |
| y | Float | The distance from the upper-left corner of the face area to the x-axis. The origin (0,0) is the upper-left corner of the image. Unit: pixel. |
| w | Float | The width of the face area, in pixels. |
| h | Float | The height of the face area, in pixels. |
smile
| Name | Type | Description |
|---|---|---|
| value | Float | The smile intensity score, from 0 to 1. A higher value indicates a more intense smile. |
| rate | Float | The confidence level of the smile detection result, from 0 to 1. A higher value indicates greater confidence. |
glasses
| Name | Type | Description |
|---|---|---|
| value | String | The glasses detection result. Valid values: None (no glasses), Wear (glasses are worn), Sunglass (sunglasses are worn). |
| rate | Float | The confidence level of the glasses detection result, from 0 to 1. A higher value indicates greater confidence. |
quality
| Name | Type | Description |
|---|---|---|
| blur | Float | The blurriness score, from 0 to 20. A higher score indicates a more blurry image. Recommended value range: 0 to 5. |
| pitch | Float | The pitch angle of the face (looking up or down). Recommended value range: -30 to 30. |
| yaw | Float | The yaw angle of the face (turning left or right). Recommended value range: -30 to 30. |
| roll | Float | The roll angle of the face (tilting side to side). Recommended value range: -30 to 30. |
respirator
| Name | Type | Description |
|---|---|---|
| value | String | The mask detection result. Valid values: Wear (a mask is worn), None (no mask). |
| rate | Float | The confidence level of the mask detection result, from 0 to 1. A higher value indicates greater confidence. |
hat
| Name | Type | Description |
|---|---|---|
| value | String | The hat detection result. Valid values: Wear (a hat is worn), None (no hat). |
| rate | Float | The confidence level of the hat detection result, from 0 to 1. A higher value indicates greater confidence. |
mustache
| Name | Type | Description |
|---|---|---|
| value | String | The mustache detection result. Valid values: Has (a mustache is present), None (no mustache). |
| rate | Float | The confidence level of the mustache detection result, from 0 to 1. A higher value indicates greater confidence. |
bang
| Name | Type | Description |
|---|---|---|
| value | String | The bangs detection result. Valid values: Has (bangs are present), None (no bangs). |
| rate | Float | The confidence level of the bangs detection result, from 0 to 1. A higher value indicates greater confidence. |
hairstyle
| Name | Type | Description |
|---|---|---|
| value | String | The hairstyle detection result. Valid values: Bald (no hair), Long (long hair), Short (short hair). |
| rate | Float | The confidence level of the hairstyle detection result, from 0 to 1. A higher value indicates greater confidence. |
Examples
Request
http(s)://[Endpoint]/green/face/detect
&<Common request parameters>
{
"bizType": "abc",
"dataId": "test2NInmO$tAON6qYUrtCRgLo-1mwxdi",
"url": "http://example.com/face1.jpeg"
}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"
}In this example, one face is detected. The face has bangs (bang.value: "Has"), short hair (hairstyle.value: "Short"), and no glasses, mask, hat, or mustache. The qualified field is false because the blur score (6.44) exceeds the threshold of 5.