> ## Documentation Index
> Fetch the complete documentation index at: https://ailabtools.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Face Analyzer API
> Face Analyzer API detects facial position, attributes, attractiveness, pose, and quality metrics from portrait images.
## 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.
### Headers
| Field | Required | Type | Description |
| :----------------- | :------- | :------- | :---------------------------------------------------- |
| `ailabapi-api-key` | YES | `string` | Application API KEY. [Get API KEY](/docs/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` | | ``0`: Close.`, ``1`: Open.` | |
## Response
**Response Field Handling Flow**
1. **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.
2. **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 |
| :----------------------------- | :-------- | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
### Response Example
```json theme={null}
,
"image_width": 0,
"image_height": 0,
"face_detail_infos": [
,
"face_detail_attributes_info": ,
"eye": ,
"eye_open": ,
"eyelid_type": ,
"eye_size":
},
"eyebrow": ,
"eyebrow_curve": ,
"eyebrow_length":
},
"gender": ,
"hair": ,
"bang": ,
"color":
},
"hat": ,
"color":
},
"head_pose": ,
"mask": ,
"mouth":
},
"moustache": ,
"nose": ,
"shape": ,
"skin": ,
"smile": 0
}
}
]
}
```
## OpenAPI
````yaml POST /api/portrait/analysis/face-analyzer
openapi: 3.0.0
info:
title: AILabAPI
description: >-
[AILabTools](https://www.ailabtools.com) is an advanced tool that
offers a vast array of simple and flexible API endpoints to suit your
specific needs. With just one [API
KEY](https://www.ailabtools.com/doc/get-api-key), you can easily call
any of the endpoints and integrate them quickly into your application or
workflow, allowing for smooth and efficient operations.
[AILabTools](https://www.ailabtools.com) is continuously evolving,
and you can anticipate even more API endpoints being added in the future,
further enhancing its capabilities and usefulness for your artificial
intelligence and machine learning requirements.
version: 1.0.0
servers:
- url: https://www.ailabapi.com
description: Production server
security:
- apiKeyAuth: []
tags:
- name: AI IMAGE
- name: AI IMAGE > Image Enhancement
- name: AI IMAGE > Image Effects
- name: AI IMAGE > Image Editing
- name: AI IMAGE > Image Scoring
- name: AI BACKGROUND REMOVAL
- name: AI BACKGROUND REMOVAL > Portrait
- name: AI BACKGROUND REMOVAL > General
- name: AI PORTRAIT
- name: AI PORTRAIT > Portrait Effects
- name: AI PORTRAIT > Portrait Enhance
- name: AI PORTRAIT > Portrait Editing
- name: AI PORTRAIT > Portrait Analysis
- name: AI COMMON
paths:
/api/portrait/analysis/face-analyzer:
post:
tags:
- AI PORTRAIT > Portrait Analysis
summary: Face Analyzer
description: >-
Face Analyzer API detects facial position, attributes, attractiveness,
pose, and quality metrics from portrait images.
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
max_face_num:
type: string
description: >-
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:
type: string
description: >-
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:
type: string
description: >-
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.
responses:
'200':
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
request_id: ''
log_id: ''
error_detail:
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
description: Success
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: ailabapi-api-key
description: API Key for authentication
````