AILabTools API - Face Analyzer - API

Request

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

Image requirements

• Image format: JPG JPEG PNG BMP
• Image size: No more than 5 MB.
• Image resolution: Less than 2000x2000px.

Header

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

Body

Field	Required	Type	Scope	Default	Example	Description
image	YES	file
max_face_num	NO	integer	[1, 120]	1		The maximum number of faces processed. When set to 1, only the largest face in the image is detected. A smaller value leads to faster processing speed.
face_attributes_type	NO	string	None Age Beauty Emotion Eye Eyebrow Gender Hair Hat Headpose Mask Mouth Moustache Nose Shape Skin Smile	None	Age,Beauty	Whether to return attributes such as age, gender, mood, etc. AttributesInfo is returned for up to 5 faces with the largest area, and AttributesInfo for more than 5 faces (the 6th and later faces) are not referenced.
need_rotate_detection	NO	integer	0 1	0		Whether to enable image rotation recognition support. When the face in the picture is rotated and there is no exif information in the picture, if you don't turn on the picture rotation recognition support, you can't detect and recognize the face in the picture correctly. If you are sure that the picture contains exif information or you are sure that the face in the input picture will not be rotated, please do not turn on this parameter. If this parameter is turned on, the overall time required may increase by hundreds of milliseconds. 0: Close. 1: Open.

Response

Processing Flow

1. Handle Public Parameters:

   First, parse and validate the Public Parameters, checking the status code or response message to ensure the request is successful and no errors are present.

2. Handle Business Parameters:

   If the public parameters are valid and no exceptions are found, proceed to process the business logic in the Business Parameters.

Public Parameters

Viewing Public Parameters and Error Codes

Business Parameters

Field	Type	Scope	Description
image_width	integer		Image width.
image_height	integer		Image height.
face_detail_infos	array		List of face information.
+face_rect	object		Face frame position.
++x	integer		The horizontal coordinate of the upper left corner of the face frame.The face frame contains the positions of the five senses of the face and expands on them, if the face frame is out of the range of the picture, it will lead to negative coordinates.If you need to intercept the complete face, you can take the negative coordinate to 0 if the complete subcompletess meets the demand.
++y	integer		The vertical coordinate of the upper left corner of the face frame. The face frame contains the positions of the five senses of the face and expands them to a certain extent. If the face frame exceeds the range of the picture, it will lead to negative coordinates. If you need to intercept the complete face, you can take the negative coordinate to 0 if the complete subcompletess meets the demand.
++width	integer		Face width.
++height	integer		Face height.
+face_detail_attributes_info	object		Face attribute information.
++age	integer	[0, 65]	Age. 65: 65 years old and above. When face_attributes_type does not contain Age or when more than 5 faces are detected, this parameter is still returned but is not informative.
++beauty	integer	[0, 100]	Beauty Score. When face_attributes_type does not contain Beauty or when more than 5 faces are detected, this parameter is still returned but is not informative.
++emotion	object		Emotional information. When face_attributes_type does not contain Emotion or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++type	integer	0 1 2 3 4 5 6	0: Neutral. 1: Happy. 2: Surprised. 3: Angry. 4: Sad. 5: Disgusted. 6: Fearful.
+++probability	float	[0, 1]	Probability of being correct.
++eye	object		Eye-related information. face_attributes_type does not contain Eye or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++glass	object		Wearing glasses.
++++type	integer	0 1 2	0: No glasses. 1: Regular glasses. 2: Sunglasses.
++++probability	float	[0, 1]	Probability of being correct.
+++eye_open	object		Closed eyes.
++++type	integer	0 1	0: No. 1: Yes.
++++probability	float	[0, 1]	Probability of being correct.
+++eyelid_type	object		Double eyelids.
++++type	integer	0 1	0: No. 1: Yes.
++++probability	float	[0, 1]	Probability of being correct.
+++eye_size	object		Eye size.
++++type	integer	0 1 2	0: Small eyes. 1: Regular eyes. 2: Large eyes.
++++probability	float	[0, 1]	Probability of being correct.
++eyebrow	object		Eyebrow information. face_attributes_type does not contain Eyebrow or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++eyebrow_density	object		Thick eyebrows.
++++type	integer	0 1	0: Sparse eyebrows. 1: Thick eyebrows.
++++probability	float	[0, 1]	Probability of being correct.
+++eyebrow_curve	object		Curved eyebrows.
++++type	integer	0 1	0: Not curved. 1: Curved eyebrows.
++++probability	float	[0, 1]	Probability of being correct.
+++eyebrow_length	object		Eyebrow length.
++++type	integer	0 1	0: Short eyebrows. 1: Long eyebrows.
++++probability	float	[0, 1]	Probability of being correct.
++gender	object		Gender information. face_attributes_type does not contain Gender or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++type	integer	0 1	0: Male. 1: Female.
+++probability	float	[0, 1]	Probability of being correct.
++hair	object		Hair information. face_attributes_type does not contain Hair or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++length	object		Hair length information.
++++type	integer	0 1 2 3 4	0: Bald. 1: Short hair. 2: Medium-length hair. 3: Long hair. 4: Tied hair.
++++probability	float	[0, 1]	Probability of being correct.
+++bang	object		Fringe (bangs) information.
++++type	integer	0 1	0: No fringe (bangs). 1: Has fringe (bangs).
++++probability	float	[0, 1]	Probability of being correct.
+++color	object		Hair color information.
++++type	integer	0 1 2 3	0: Black. 1: Blonde. 2: Brown. 3: Gray/White.
++++probability	float	[0, 1]	Probability of being correct.
++hat	object		Hat information. face_attributes_type does not contain Hat or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++style	object		Hat wearing status information.
++++type	integer	0 1 2 3	0: No hat. 1: Regular hat. 2: Helmet. 3: Security hat.
++++probability	float	[0, 1]	Probability of being correct.
+++color	object		Hat color.
++++type	integer	0 1 2 3 4 5 6	0: No hat. 1: Red shades. 2: Yellow shades. 3: Blue shades. 4: Black shades. 5: Gray/White shades. 6: Mixed colors.
++++probability	float	[0, 1]	Probability of being correct.
++head_pose	object		Face offset information. face_attributes_type does not contain HeadPose or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++pitch	integer	[-30, 30]	Vertical Offset.
+++yaw	integer	[-30, 30]	Horizontal Offset.
+++pitch	integer	[-180, 180]	Planar Rotation.
++mask	object		Mask wearing information. face_attributes_type does not contain Mask or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++type	integer	0 1 2 3 4	0: No mask. 1: Mask without covering face. 2: Mask covering chin. 3: Mask covering mouth. 4: Correctly worn mask.
+++probability	float	[0, 1]	Probability of being correct.
++mouth	object		Mouth information. face_attributes_type does not contain Mouth or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++mouth_open	object		Mouth open.
++++type	integer	0 1	0: No. 1: Yes.
++++probability	float	[0, 1]	Probability of being correct.
++moustache	object		Facial hair information. face_attributes_type does not contain Moustache or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++type	integer	0 1	0: No facial hair. 1: Facial hair.
+++probability	float	[0, 1]	Probability of being correct.
++nose	object		Nose information. face_attributes_type does not contain Nose or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++type	integer	0 1 2 3	0: Upturned nose. 1: Hooked nose. 2: Normal. 3: Round-tipped nose.
+++probability	float	[0, 1]	Probability of being correct.
++shape	object		Face shape information. face_attributes_type does not contain Shape or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++type	integer	0 1 2 3 4	0: Square face. 1: Triangular face. 2: Oval face. 3: Heart-shaped face. 4: Round face.
+++probability	float	[0, 1]	Probability of being correct.
++skin	object		Skin color information. face_attributes_type does not contain Skin or when more than 5 faces are detected, this parameter is still returned but is not informative.
+++type	integer	0 1 2 3	0: Yellow skin. 1: Brown skin. 2: Black skin. 3: White skin.
+++probability	float	[0, 1]	Probability of being correct.
++smile	integer	[0,100]	Smile Rating. face_attributes_type does not contain Smile or when more than 5 faces are detected, this parameter is still returned but is not informative.

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,
  "face_detail_infos": [
    {
      "face_rect":                   {
        "x":      0,
        "y":      0,
        "width":  0,
        "height": 0
      },
      "face_detail_attributes_info": {
        "age":       0,
        "beauty":    0,
        "emotion":   {
          "type":        0,
          "probability": 0
        },
        "eye":       {
          "glass":       {
            "type":        0,
            "probability": 0.99936753511429
          },
          "eye_open":    {
            "type":        0,
            "probability": 0.99949336051941
          },
          "eyelid_type": {
            "type":        1,
            "probability": 0.75467920303345
          },
          "eye_size":    {
            "type":        2,
            "probability": 0.59152442216873
          }
        },
        "eyebrow":   {
          "eyebrow_density": {
            "type":        0,
            "probability": 0
          },
          "eyebrow_curve":   {
            "type":        0,
            "probability": 0
          },
          "eyebrow_length":  {
            "type":        0,
            "probability": 0
          }
        },
        "gender":    {
          "type":        0,
          "probability": 0
        },
        "hair":      {
          "length": {
            "type":        0,
            "probability": 0
          },
          "bang":   {
            "type":        0,
            "probability": 0
          },
          "color":  {
            "type":        0,
            "probability": 0
          }
        },
        "hat":       {
          "style": {
            "type":        0,
            "probability": 0
          },
          "color": {
            "type":        0,
            "probability": 0
          }
        },
        "head_pose": {
          "pitch": 0,
          "yaw":   0,
          "roll":  0
        },
        "mask":      {
          "type":        0,
          "probability": 0
        },
        "mouth":     {
          "mouth_open": {
            "type":        0,
            "probability": 0
          }
        },
        "moustache": {
          "type":        0,
          "probability": 0
        },
        "nose":      {
          "type":        2,
          "probability": 0.75233882665634
        },
        "shape":     {
          "type":        0,
          "probability": 0
        },
        "skin":      {
          "type":        0,
          "probability": 0
        },
        "smile":     0
      }
    }
  ]
}

Code example

• Introduction
• Code example