AILabTools API - Face Analyzer Advanced - API

draft: true

Important Announcement: The API Documentation Has Been Fully Updated

This API documentation has been completely restructured with an improved and clearer format. The current page will no longer receive active updates or maintenance. For the most accurate and up-to-date information, please switch to the new documentation.

View New Docs

Request

URL: https://www.ailabapi.com/api/portrait/analysis/face-analyzer-advanced
Method: POST
Content-Type: multipart/form-data

Image requirements

Image format: JPG JPEG PNG BMP
Image size: No more than 20 MB.
Image resolution: Larger than 32×32px, smaller than 4096×4096px, face no smaller than 64×64px.

Headers

Field	Required	Type	Description
`ailabapi-api-key`	YES	`string`	Application API KEY. Get API KEY

Body

Field	Required	Type
`image`	YES	`file`

Response

Response Field Handling Flow

Handle Public Response Fields

Parse and validate the Public Response Fields, checking the status code or response message to ensure the request is successful and error-free.
Handle Business Response Fields

If the Public Response Fields are valid and error-free, proceed with processing the business logic in the Business Response Fields.

Public Response Fields

Viewing Public Response Fields and Error Codes

Business Response Fields

Field	Type	Scope	Description
`data`	`object`
+`pupils`	`array of float`		The center point coordinates and radius of the left and right pupils, with 6 floating-point values per face, in the order of `[left_iris_cenpt.x, left_iris_cenpt.y, left_iris_radius, right_iris_cenpt.x, right_iris_cenpt.y, right_iris_radius]`. If multiple faces are detected, results are returned in order.
+`gender_list`	`array of integer`	`0` `1`	Gender. If multiple faces are detected, results are returned in order. `0`: Female. `1`: Male.
+`expressions`	`array of integer`	`0` `1`	Expression. If multiple faces are detected, results are returned in order. `0`: Neutral. `1`: Smile.
+`face_count`	`integer`		Number of faces.
+`landmarks`	`array of float`		Facial landmark detection results. A set of landmark coordinates is returned for each face, represented as (x0, y0, x1, y1, …). If multiple faces are detected, results are returned in order.
+`landmark_count`	`integer`	`105`	Number of facial landmarks. distributed as follows: Eyebrows: 24 points Eyes: 32 points Nose: 6 points Mouth: 34 points Outer contour: 9 points
+`beauty_list`	`array of float`	[0, 100]	Attractiveness score. A higher score indicates a higher level of attractiveness. If multiple faces are detected, results are returned in order.
+`hat_list`	`array of integer`	`0` `1`	Whether wearing a hat. If multiple faces are detected, results are returned in order. `0`: No. `1`: Yes.
+`face_probability_list`	`array of float`	[0, 1]	Probability of a face. If multiple faces are detected, results are returned in order.
+`glasses`	`array of integer`	`0` `1` `2`	Whether wearing glasses. If multiple faces are detected, results are returned in order. `0`: No glasses. `1`: Wearing regular glasses. `2`: Wearing sunglasses.
+`face_rectangles`	`array of integer`		Face bounding box, represented as `[left, top, width, height]`. If multiple faces are detected, results are returned in order.
+`pose_list`	`array of float`		Face pose, in the format `[yaw, pitch, roll]`. If multiple faces are detected, results are returned in order. `yaw`: left-right angle. Range: `[-90, 90]`. `pitch`: up-down angle. Range: `[-90, 90]`. `roll`: in-plane rotation angle. Range: `[-180, 180]`.
+`age_list`	`array of integer`	[0, 100]	Age. If multiple faces are detected, results are returned in order.
+`dense_feature_length`	`integer`	`1024`	The feature dimension returned by face recognition.
+`masks`	`array of integer`	`0` `1` `2`	Whether wearing a mask. If multiple faces are detected, results are returned in order. `0`: No. `1`: Yes. `2`: Mask worn incorrectly.
+`qualities`	`object`		Face quality score, where a higher score indicates better suitability for recognition.
++`score_list`	`array of float`	[0, 100]	Overall quality score, where a higher score indicates better suitability for recognition. It is recommended to set a threshold of ≥85 during recognition: a score above 85 indicates high overall image quality, while a score below 85 indicates lower overall image quality. If multiple faces are detected, results are returned in order.
++`blur_list`	`array of float`	[0, 100]	Face blur score indicating the impact of blurriness on recognition, where a higher score is more favorable for recognition. It is recommended to set a threshold of ≥85 during recognition: a score above 85 indicates a lower likelihood of the image being blurry, while a score below 85 indicates a higher likelihood of blurriness. If multiple faces are detected, results are returned in order.
++`fnf_list`	`array of float`	[0, 100]	Score indicating whether the target is a face and its impact on recognition, where a higher score is more favorable for recognition. It is recommended to set a threshold of ≥85 during recognition: a score above 85 indicates a higher probability that the image is a face, while a score below 85 indicates a lower probability. If multiple faces are detected, results are returned in order.
++`glass_list`	`array of float`	[0, 100]	Score indicating the impact of upper-face occlusion (e.g., glasses) on recognition, where a higher score is more favorable for recognition. It is recommended to set a threshold of ≥85 during recognition: a score above 85 indicates a lower probability of wearing glasses, while a score below 85 indicates a higher probability. If multiple faces are detected, results are returned in order.
++`illu_list`	`array of float`	[0, 100]	Score indicating the impact of lighting on recognition, where a higher score is more favorable for recognition. It is recommended to set a threshold of ≥85 during recognition: a score above 85 indicates a higher probability that the image has good lighting, while a score below 85 indicates a lower probability. If multiple faces are detected, results are returned in order.
++`mask_list`	`array of float`	[0, 100]	Score indicating the impact of lower-face occlusion (e.g., mask) on recognition, where a higher score is more favorable for recognition. It is recommended to set a threshold of ≥85 during recognition: a score above 85 indicates a lower probability of wearing a mask, while a score below 85 indicates a higher probability. If multiple faces are detected, results are returned in order.
++`noise_list`	`array of float`	[0, 100]	Score indicating the impact of image noise on recognition, where a higher score is more favorable for recognition. It is recommended to set a threshold of ≥85 during recognition: a score above 85 indicates a lower probability of image noise, while a score below 85 indicates a higher probability. If multiple faces are detected, results are returned in order.
++`pose_list`	`array of float`	[0, 100]	Score indicating the impact of face pose on recognition, where a higher score is more favorable for recognition. It is recommended to set a threshold of ≥85 during recognition: a score above 85 indicates a higher probability of the face being frontal, while a score below 85 indicates a lower probability. If multiple faces are detected, results are returned in order.

Response Example

{
  "request_id":     "",
  "log_id":         "",
  "error_code":     0,
  "error_code_str": "",
  "error_msg":      "",
  "error_detail":   {
    "status_code":  200,
    "code":         "",
    "code_message": "",
    "message":      ""
  },
  "image_width":    0,
  "image_height":   0,
  "data":           {
    "beauty_list":           [
      52
    ],
    "face_rectangles":       [
      189,
      152,
      307,
      412
    ],
    "qualities":             {
      "score_list": [
        96.41
      ],
      "noise_list": [
        98.3
      ],
      "blur_list":  [
        99.82
      ],
      "fnf_list":   [
        100
      ],
      "glass_list": [
        100
      ],
      "mask_list":  [
        86.71
      ],
      "illu_list":  [
        99.96
      ],
      "pose_list":  [
        95.15
      ]
    },
    "dense_feature_length":  1024,
    "pupils":                [
97,
93,
85,
95,
45,
85
    ],
    "gender_list":           [
      1
    ],
    "pose_list":             [
84,
      -2.23,
      -3.3
    ],
    "masks":                 [
      0
    ],
    "face_probability_list": [
98
    ],
    "hat_list":              [
      0
    ],
    "landmark_count":        105,
    "age_list":              [
      39
    ],
    "glasses":               [
      0
    ],
    "landmarks":             [
84,
4,
35,
43,
93,
62,
17,
41,
42,
44,
93,
53,
59,
6,
53,
61,
94,
02,
65,
05,
97,
66,
33,
58,
47,
46,
65,
67,
46,
5,
25,
1,
97,
      285,
23,
84,
5,
1,
31,
7,
78,
35,
83,
41,
46,
85,
84,
42,
03,
34,
29,
87,
11,
3,
89,
29,
83,
46,
42,
38,
65,
8,
55,
5,
28,
32,
54,
95,
26,
92,
74,
13,
47,
72,
61,
52,
06,
53,
9,
67,
22,
26,
41,
94,
53,
41,
52,
38,
45,
33,
04,
87,
57,
02,
19,
97,
96,
63,
44,
84,
17,
31,
3,
36,
3,
93,
45,
53,
97,
42,
81,
33,
81,
48,
93,
17,
66,
53,
7,
48,
34,
64,
58,
33,
8,
18,
32,
05,
01,
31,
69,
18,
79,
82,
8,
36,
22,
34,
04,
25,
19,
49,
18,
88,
15,
15,
17,
65,
07,
47,
25,
12,
05,
85,
68,
71,
35,
26,
99,
6,
75,
11,
05,
5,
32,
86,
39,
15,
54,
99,
1,
61,
77,
35,
76,
72,
64,
9,
31,
65,
77,
03,
73,
77,
57,
94,
46,
34,
6,
33,
4,
7,
69,
94,
09,
63,
16,
93,
75,
35,
01,
47,
83,
88,
73,
53,
2,
24,
97,
44
    ],
    "expressions":           [
      1
    ],
    "face_count":            1
  }
}

AILabTools API - Face Analyzer Advanced - API

draft: true​

Request​

Image requirements​

Headers​

Body​

Response​

Public Response Fields​

Business Response Fields​

Response Example​

Sample Code​