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:

Authorization: Bearer YOUR_API_KEY

Face Verification

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

Endpoint

POST /v1/face/verify

Parameters

Parameter

Type

Required

Description

image1

file

✅

First face image (JPG, PNG, WebP)

image2

file

✅

Second face image (JPG, PNG, WebP)

Request Example

curl -X POST https://api.zaits.net/v1/face/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

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();

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()

Response

{
  "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

POST /v1/face/analyze

Parameters

Parameter

Type

Required

Description

image

file

✅

Face image to analyze

attributes

array

❌

Analysis types (default: all)

Available Attributes

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

Request Example

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

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();

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()

Response

{
  "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

POST /v1/face/detect

Parameters

Parameter

Type

Required

Description

image

file

✅

Image to analyze

min_confidence

number

❌

Minimum confidence threshold (0-1)

Request Example

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

{
  "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

POST /v1/face/landmarks

Parameters

Parameter

Type

Required

Description

image

file

✅

Face image

model

string

❌

Landmark model (68_point, 5_point)

Request Example

curl -X POST https://api.zaits.net/v1/face/landmarks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "model=68_point"

Response

{
  "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

POST /v1/face/liveness

Parameters

Parameter

Type

Required

Description

image

file

✅

Face image to check

threshold

number

❌

Liveness threshold (0-1, default: 0.5)

Request Example

curl -X POST https://api.zaits.net/v1/face/liveness \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "threshold=0.7"

Response

{
  "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

{
  "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 | OCR API

PreviousQuick Start Guide NextFace Matching API

Last updated 1 month ago