# Face Recognition API

The Face Recognition API provides powerful computer vision capabilities for face verification, analysis, detection, and liveness checking.

## Base URL

```
https://api.zaits.net/v1/face
```

## Authentication

All requests require your API key in the Authorization header:

```http
Authorization: Bearer YOUR_API_KEY
```

***

## Face Verification

Compare two faces to determine if they belong to the same person.

### Endpoint

```http
POST /v1/face/verify
```

### Parameters

| Parameter | Type | Required | Description                        |
| --------- | ---- | -------- | ---------------------------------- |
| `image1`  | file | Yes      | First face image (JPG, PNG, WebP)  |
| `image2`  | file | Yes      | Second face image (JPG, PNG, WebP) |

### Request Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.zaits.net/v1/face/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image1=@face1.jpg" \
  -F "image2=@face2.jpg"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const formData = new FormData();
formData.append("image1", file1);
formData.append("image2", file2);

const response = await fetch("https://api.zaits.net/v1/face/verify", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: formData,
});

const result = await response.json();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

files = {
    'image1': open('face1.jpg', 'rb'),
    'image2': open('face2.jpg', 'rb')
}

response = requests.post(
    'https://api.zaits.net/v1/face/verify',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    files=files
)

result = response.json()
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "data": {
    "verified": true,
    "confidence": 0.89,
    "distance": 0.32,
    "threshold": 0.6,
    "processing_time": 1.2,
    "face1_detected": true,
    "face2_detected": true
  }
}
```

### Response Fields

| Field             | Type    | Description                                     |
| ----------------- | ------- | ----------------------------------------------- |
| `verified`        | boolean | Whether faces match (true/false)                |
| `confidence`      | number  | Confidence score (0-1, higher = more confident) |
| `distance`        | number  | Face distance metric (lower = more similar)     |
| `threshold`       | number  | Threshold used for verification decision        |
| `processing_time` | number  | Processing time in seconds                      |
| `face1_detected`  | boolean | Whether face was detected in first image        |
| `face2_detected`  | boolean | Whether face was detected in second image       |

***

## Face Analysis

Analyze facial attributes including age, gender, emotion, and more.

### Endpoint

```http
POST /v1/face/analyze
```

### Parameters

| Parameter    | Type  | Required | Description                   |
| ------------ | ----- | -------- | ----------------------------- |
| `image`      | file  | Yes      | Face image to analyze         |
| `attributes` | array | No       | Analysis types (default: all) |

### Available Attributes

* `age` - Estimate age
* `gender` - Detect gender
* `emotion` - Recognize emotions
* `race` - Detect ethnicity (optional)

### Request Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.zaits.net/v1/face/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@face.jpg" \
  -F "attributes=[\"age\", \"gender\", \"emotion\"]"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const formData = new FormData();
formData.append("image", file);
formData.append("attributes", JSON.stringify(["age", "gender", "emotion"]));

const response = await fetch("https://api.zaits.net/v1/face/analyze", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: formData,
});

const result = await response.json();
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

files = {'image': open('face.jpg', 'rb')}
data = {'attributes': json.dumps(['age', 'gender', 'emotion'])}

response = requests.post(
    'https://api.zaits.net/v1/face/analyze',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    files=files,
    data=data
)

result = response.json()
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "data": {
    "age": 28,
    "gender": {
      "prediction": "Male",
      "confidence": 0.92
    },
    "emotion": {
      "dominant_emotion": "happy",
      "emotions": {
        "happy": 0.85,
        "neutral": 0.12,
        "surprise": 0.02,
        "sad": 0.01,
        "angry": 0.0,
        "disgust": 0.0,
        "fear": 0.0
      }
    },
    "region": {
      "x": 45,
      "y": 67,
      "w": 120,
      "h": 140
    },
    "processing_time": 0.8
  }
}
```

***

## Face Detection

Detect and locate all faces in an image.

### Endpoint

```http
POST /v1/face/detect
```

### Parameters

| Parameter        | Type   | Required | Description                        |
| ---------------- | ------ | -------- | ---------------------------------- |
| `image`          | file   | Yes      | Image to analyze                   |
| `min_confidence` | number | No       | Minimum confidence threshold (0-1) |

### Request Example

```bash
curl -X POST https://api.zaits.net/v1/face/detect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@group_photo.jpg" \
  -F "min_confidence=0.8"
```

### Response

```json
{
  "success": true,
  "data": {
    "faces_detected": 3,
    "faces": [
      {
        "id": 1,
        "region": {
          "x": 45,
          "y": 67,
          "w": 120,
          "h": 140
        },
        "confidence": 0.99
      },
      {
        "id": 2,
        "region": {
          "x": 200,
          "y": 50,
          "w": 115,
          "h": 130
        },
        "confidence": 0.95
      },
      {
        "id": 3,
        "region": {
          "x": 350,
          "y": 80,
          "w": 110,
          "h": 125
        },
        "confidence": 0.87
      }
    ],
    "processing_time": 1.1
  }
}
```

***

## Face Landmarks

Extract detailed facial landmark points for precise face analysis.

### Endpoint

```http
POST /v1/face/landmarks
```

### Parameters

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `image`   | file   | Yes      | Face image                             |
| `model`   | string | No       | Landmark model (`68_point`, `5_point`) |

### Request Example

```bash
curl -X POST https://api.zaits.net/v1/face/landmarks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@face.jpg" \
  -F "model=68_point"
```

### Response

```json
{
  "success": true,
  "data": {
    "landmarks": {
      "left_eye": { "x": 78, "y": 95 },
      "right_eye": { "x": 142, "y": 93 },
      "nose_tip": { "x": 110, "y": 125 },
      "mouth_left": { "x": 85, "y": 155 },
      "mouth_right": { "x": 135, "y": 157 },
      "chin": { "x": 110, "y": 180 },
      "left_eyebrow": [
        { "x": 65, "y": 85 },
        { "x": 70, "y": 80 },
        { "x": 80, "y": 82 }
      ]
    },
    "face_region": {
      "x": 45,
      "y": 67,
      "w": 120,
      "h": 140
    },
    "processing_time": 0.9
  }
}
```

***

## Liveness Detection

Verify if a face image is from a live person (anti-spoofing).

### Endpoint

```http
POST /v1/face/liveness
```

### Parameters

| Parameter   | Type   | Required | Description                            |
| ----------- | ------ | -------- | -------------------------------------- |
| `image`     | file   | Yes      | Face image to check                    |
| `threshold` | number | No       | Liveness threshold (0-1, default: 0.5) |

### Request Example

```bash
curl -X POST https://api.zaits.net/v1/face/liveness \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@selfie.jpg" \
  -F "threshold=0.7"
```

### Response

```json
{
  "success": true,
  "data": {
    "is_live": true,
    "confidence": 0.94,
    "anti_spoofing_score": 0.89,
    "threshold": 0.7,
    "checks": {
      "texture_analysis": 0.92,
      "depth_analysis": 0.88,
      "motion_analysis": 0.91
    },
    "processing_time": 1.3
  }
}
```

***

## Error Responses

### Common Errors

| Error Code                | HTTP Status | Description                                 |
| ------------------------- | ----------- | ------------------------------------------- |
| `no_face_detected`        | 400         | No face found in the image                  |
| `multiple_faces_detected` | 400         | Multiple faces found (single face expected) |
| `image_too_small`         | 400         | Image resolution too low for analysis       |
| `image_too_large`         | 413         | Image file size exceeds 5MB limit           |
| `unsupported_format`      | 400         | Image format not supported                  |
| `insufficient_quality`    | 400         | Image quality too low for reliable analysis |

### Error Response Format

```json
{
  "success": false,
  "error": {
    "code": "no_face_detected",
    "message": "No face was detected in the provided image",
    "details": {
      "image": "image1",
      "suggestions": [
        "Ensure the face is clearly visible",
        "Check image lighting and quality",
        "Try a different angle or photo"
      ]
    }
  }
}
```

## Best Practices

### Image Requirements

* **Format:** JPG, JPEG, PNG, WebP
* **Size:** Max 5MB per image
* **Resolution:** Min 100x100px, recommended 300x300px+
* **Face size:** At least 80x80 pixels for reliable detection
* **Quality:** Clear, well-lit images work best

### Performance Tips

* **Resize large images** before uploading to reduce processing time
* **Use JPEG format** for better compression without quality loss
* **Ensure good lighting** for better accuracy
* **Crop to face area** when possible to improve performance

### Security Considerations

* Images are processed and **not stored** on our servers
* All API communication uses **HTTPS encryption**
* **Rotate API keys** regularly for security
* **Never expose API keys** in client-side code

***

**Next:** [Face Matching API](/api/api-reference/face-matching.md) | [OCR API](/api/api-reference/ocr.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://zaits.gitbook.io/api/api-reference/face.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.