Name: Face Analyzer – Detect Facial Attributes | Free · $10/mo | API.market
Brand: ailabtools
SKU: api-ailabtools-face-analyzer
Availability: InStock
Author: API Market

# 👤🔍 Face Analyzer API

The Face Analyzer API provides comprehensive facial detection and attribute analysis from an input image. It detects faces and extracts detailed information—such as age, beauty score, emotion, eye status, eyebrow characteristics, gender, hair style and color, head pose, mask usage, and more. Developers can configure the maximum number of faces to process and choose specific attributes to return. This API is optimized for images under 2000×2000 px and supports a variety of common image formats.

## Features
- **Multi-Face Detection**: Detects up to 120 faces per image. When `max_face_num` is set to 1, only the largest face is analyzed for faster processing.
- **Customizable Attribute Extraction**: Return facial attributes like Age, Beauty, Emotion, Eye, Eyebrow, Gender, Hair, Hat, Headpose, Mask, Mouth, Moustache, Nose, Shape, Skin, and Smile.
- **Rotation Detection Support**: Optionally enable rotation detection to correctly recognize rotated faces when EXIF data is absent.
- **Detailed Face Data**: Provides precise face rectangle coordinates and probabilistic scores for each attribute.

## Use-Cases
- **Security and Surveillance**: Detect and analyze faces for identification and monitoring purposes.
- **Photo Management and Social Media**: Tag and organize images based on facial features and attributes.
- **User Experience Enhancements**: Improve personalization and interactive applications by integrating facial attribute analysis.
- **Research and Analytics**: Gather demographic and emotion data from large image datasets for analysis.

## API Documentation

### Endpoint
```bash
curl -X 'POST' \
  'https://prod.api.market/api/v1/ailabtools/face-analyzer/portrait/analysis/detect-face-attributes' \
  -H 'accept: application/json' \
  -H 'x-magicapi-key: <YOUR API MARKET KEY>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'image=@2024101008.jpg;type=image/jpeg' \
  -F 'max_face_num=1' \
  -F 'face_attributes_type=Age,Beauty,Emotion,Eye,Eyebrow,Gender,Hair,Hat,Headpose,Mask,Mouth,Moustache,Nose,Shape,Skin,Smile' \
  -F 'need_rotate_detection='
```
### Request

#### Image Requirements
- **Formats:** JPG, JPEG, PNG, BMP
- **Max Size:** 5 MB
- **Resolution:** Less than 2000×2000 px

#### Request Body Fields

| Field                   | Required | Type    | Range/Options                                           | Default | Example       | Description                                                                                                                                                   |
|-------------------------|:--------:|---------|---------------------------------------------------------|---------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `image`                 | Yes      | file    | -                                                       | -       |               | The input image for analysis.                                                                                                                                |
| `max_face_num`          | No       | integer | [1, 120]                                               | 1       | 5             | Maximum number of faces to process. If set to 1, only the largest face is analyzed.                                                                           |
| `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` | Comma-separated list of facial attributes to return. Detailed attributes are provided for up to 5 faces with the largest area; additional faces return minimal info. |
| `need_rotate_detection` | No       | integer | 0 or 1                                                | 0       | 1             | Whether to enable rotation detection. 0 = disabled; 1 = enabled. Increases processing time if enabled.                                                       |

### Response

#### Public Response Fields
The API returns the following standard fields:
- `request_id`
- `log_id`
- `error_code`
- `error_msg`
- `error_detail` (including `status_code`, `code`, `code_message`, `message`)

#### Business Response Fields

| Field                | Type    | Description                                             |
|----------------------|---------|---------------------------------------------------------|
| `image_width`        | integer | Width of the input image.                               |
| `image_height`       | integer | Height of the input image.                              |
| `face_detail_infos`  | array   | A list of detected face details.                      |

Each element in `face_detail_infos` includes:
- **Face Rectangle (`face_rect`)**:
  - `x`: Horizontal coordinate of the upper left corner.
  - `y`: Vertical coordinate of the upper left corner.
  - `width`: Width of the face rectangle.
  - `height`: Height of the face rectangle.
- **Face Attribute Information (`face_detail_attributes_info`)**:
  - `age`: Estimated age (0–65; 65 represents 65 and above).
  - `beauty`: Beauty score (0–100).
  - `emotion`: Contains:
    - `type`: Emotion type (0: Neutral, 1: Happy, 2: Surprised, 3: Angry, 4: Sad, 5: Disgusted, 6: Fearful).
    - `probability`: Confidence probability (0 to 1).
  - **Additional Attributes**: Detailed information on eye (including glasses, eye openness, eyelid type, eye size), eyebrow (density, curve, length), gender, hair (length, fringe, color), hat (style and color), head pose (pitch, yaw, roll), mask, mouth (mouth open), moustache, nose, face shape, skin tone, and smile score. Each attribute is accompanied by a probability value indicating confidence.

#### Response
```bash
{
  "error_code": 0,
  "error_detail": {
    "status_code": 200,
    "code": "",
    "code_message": "",
    "message": ""
  },
  "face_detail_infos": [
    {
      "face_rect": {
        "y": 1279,
        "width": 637,
        "height": 944,
        "x": 1800
      },
      "face_detail_attributes_info": {
        "mouth": {
          "mouth_open": {
            "type": 0,
            "probability": 0.7003469
          }
        },
        "skin": {
          "type": 0,
          "probability": 0.84199
        },
        "eyebrow": {
          "eyebrow_density": {
            "type": 1,
            "probability": 0.7625521
          },
          "eyebrow_curve": {
            "probability": 0.7485373,
            "type": 0
          },
          "eyebrow_length": {
            "type": 1,
            "probability": 0.70831233
          }
        },
        "hat": {
          "style": {
            "type": 2,
            "probability": 0.9687969
          },
          "color": {
            "type": 2,
            "probability": 0.28146878
          }
        },
        "beauty": 64,
        "smile": 25,
        "gender": {
          "probability": 0.980477,
          "type": 1
        },
        "hair": {
          "length": {
            "type": 4,
            "probability": 0.45162237
          },
          "bang": {
            "type": 0,
            "probability": 0.92399246
          },
          "color": {
            "type": 0,
            "probability": 0.6028447
          }
        },
        "head_pose": {
          "yaw": -29,
          "roll": 12,
          "pitch": -2
        },
        "mask": {
          "type": 0,
          "probability": 0.9753338
        },
        "emotion": {
          "type": 0,
          "probability": 0.9850573
        },
        "eye": {
          "eye_open": {
            "type": 0,
            "probability": 0.9308251
          },
          "eyelid_type": {
            "type": 1,
            "probability": 0.6554697
          },
          "eye_size": {
            "type": 2,
            "probability": 0.4093857
          },
          "glass": {
            "type": 0,
            "probability": 0.8565918
          }
        },
        "nose": {
          "type": 2,
          "probability": 0.72973627
        },
        "shape": {
          "type": 2,
          "probability": 0.6998119
        },
        "age": 28,
        "moustache": {
          "type": 0,
          "probability": 0.9981092
        }
      }
    }
  ],
  "face_model_version": "3.0",
  "image_height": 4000,
  "image_width": 3000,
  "log_id": "string",
  "request_id": "string"
}

```
## Status Codes & Error Handling

| Field        | Description                                                                                   |
|--------------|-----------------------------------------------------------------------------------------------|
| `error_code` | A value of 0 indicates success; non-zero values represent errors (e.g., invalid input or file format issues). |
| `error_msg`  | Provides a brief description of any errors encountered.                                       |
| `status_code`| Standard HTTP status codes (e.g., 200 for success, 400 for bad requests). Use these along with `error_code` to determine the request outcome. |

## SEO Keywords
Face Analyzer API, facial detection, facial attribute extraction, face recognition API, emotion detection, age estimation, gender recognition, AI face analysis, computer vision face attributes, facial analysis tool

Analyze facial features, emotion, age, gender, and more from any image. Detects up to 120 faces. Free 10 calls/mo, from $10/mo. Start free on API.market.

Face Analyzer – Detect Facial Attributes | Free · $10/mo | API.market

BASIC

AILabTools

ULTRA

MEGA

Analyze facial features and quality metrics in images with our comprehensive Face Analyzer API, providing detailed face location, attributes, or quality scores.