Face Detection (Face)
Updated at：2025-11-03
Function description
- Detect faces in the input image and provide face locations, 72 key point coordinates, and related facial attribute data.
- The detection response time depends on the number of faces in the image. A larger number of faces may slightly slow down the response.
- Typical application scenarios: e.g., Facial Attribute Analysis, Processing Analysis Based on Key Face Points, Facial Marketing Campaigns, etc.
- Specific coordinates for facial features are marked, along with the 72 key point coordinates. However, these do not include detailed descriptions of the corresponding positions.
Request parameters
None
Response parameters
| Parameters | Types | Required or not | Description |
|---|---|---|---|
| log_id | uint64 | Yes | Log ID |
| result_num | uint32 | Yes | Face count |
| result | object[] | Yes | Collection of facial attribute objects |
| +age | double | No | Age is returned when face_fields includes age. |
| +beauty | double | No | Beauty score ranges from 0 to 100; the higher the score, the more beautiful. It is returned when face_fields includes beauty. |
| +location | object | Yes | Position of face in the image |
| ++left | uint32 | Yes | Distance from face region to the left boundary |
| ++top | uint32 | Yes | Distance from face region to the upper boundary |
| ++width | uint32 | Yes | Width of face region |
| ++height | uint32 | Yes | Height of face region |
| +face_probability | double | Yes | Face confidence, ranging 0-1 |
| +rotation_angle | int32 | Yes | Clockwise rotation angle of face frame relative to vertical direction, [-180,180] |
| +yaw | double | Yes | 3D rotation - left/right rotation angle: [-90 (left), 90(right)] |
| +pitch | double | Yes | 3D rotation - pitch angle [-90 (Upper), 90 (Lower)] |
| +roll | double | Yes | In-plane rotation angle [-180 (counterclockwise), 180(clockwise)] |
| +expression | uint32 | No | Expression: 0 for no smile or laugh, 1 for smile, and 2 for laugh. This is returned when face_fields includes expression. |
| +expression_probability | double | No | Expression confidence ranges from 0 to 1 and is returned when face_fields includes expression. |
| +faceshape | object[] | No | Face shape confidence is returned when face_fields includes faceshape. |
| ++type | string | Yes | Face shape: square/triangle/oval/heart/round |
| ++probability | double | Yes | Confidence: 0~1 |
| +gender | string | No | Gender: male or female. This is returned when face_fields includes gender. |
| +gender_probability | double | No | Gender confidence, ranging from 0 to 1, is returned when face_fields includes gender. |
| +glasses | uint32 | No | Glasses: 0 for no glasses, 1 for ordinary glasses, and 2 for sunglasses. This is returned when face_fields includes glasses. |
| +glasses_probability | double | No | Glasses confidence, ranging from 0 to 1, is returned when face_fields includes glasses. |
| +landmark | object[] | No | Four key point positions, including left eye center, right eye center, nose tip, and mouth center, are returned when face_fields includes landmark. |
| ++x | uint32 | No | X-coordinate |
| ++y | uint32 | No | Y-coordinate |
| +landmark72 | object[] | No | Seventy-two feature point positions are illustrated and returned when face_fields includes landmark. |
| ++x | uint32 | No | X-coordinate |
| ++y | uint32 | No | Y-coordinate |
| +race | string | No | Race options include yellow, white, black, and Arab, and are returned when face_fields includes race. |
| +race_probability | double | No | Race confidence, ranging from 0 to 1, is returned when face_fields includes race. |
| +qualities | object | No | Face quality information is returned when face_fields includes qualities. |
| ++occlusion | object | Yes | Probability of occlusion for facial parts, [0, 1] (pending launch) |
| +++left_eye | double | Yes | Left eye |
| +++right_eye | double | Yes | Right eye |
| +++nose | double | Yes | Nose |
| +++mouth | double | Yes | Mouth |
| +++left_cheek | double | Yes | Left cheek |
| +++right_cheek | double | Yes | Right cheek |
| +++chin | double | Yes | Chin |
| ++blur | double | Yes | Face blurriness, [0, 1]. 0 indicates clear; 1 indicates blurry (pending launch) |
| ++illumination | - | Yes | The value range is [0,255], indicating the lighting level of the facial area (pending launch) |
| ++completeness | - | Yes | Face completeness, [0, 1]. 0 indicates complete; 1 indicates incomplete (pending launch) |
| ++type | object | Yes | Real face/cartoon face confidence |
| +++human | - | Yes | Real face confidence, [0, 1] |
| +++cartoon | - | Yes | Cartoon face confidence, [0, 1] |
Response example
Plain Text
1{
2 "result_num": 1,
3 "result": [
4 {
5 "location": {
6 "left": 90,
7 "top": 92,
8 "width": 111,
9 "height": 99
10 },
11 "face_probability": 1,
12 "rotation_angle": 6,
13 "yaw": 11.61234664917,
14 "pitch": -0.30852827429771,
15 "roll": 8.8044967651367,
16 "landmark": [
17 {
18 "x": 105,
19 "y": 110
20 },
21 ...
22 ],
23 "landmark72": [
24 {
25 "x": 88,
26 "y": 109
27 },
28 ...
29 ],
30 "gender": "male",
31 "gender_probability": 0.99358034133911,
32 "glasses": 0,
33 "glasses_probability": 0.99991309642792,
34 "race": "yellow",
35 "race_probability": 0.99960690736771,
36 "qualities": {
37 "occlusion": {
38 "left_eye": 0.000085282314103097,
39 "right_eye": 0.00001094374601962,
40 "nose": 3.2677664307812e-7,
41 "mouth": 2.6582130940866e-10,
42 "left_cheek": 8.752236624332e-8,
43 "right_cheek": 1.0212766454742e-7,
44 "chin": 4.2632994357028e-10
45 },
46 "blur": 4.5613666312237e-41,
47 "illumination": 0,
48 "completeness": 0,
49 "type": {
50 "human": 0.98398965597153,
51 "cartoon": 0.016010366380215
52 }
53 }
54 }
55 ],
56 "log_id": 2418894422
57}