# Face Recognition API

The Face Recognition API provides AI-powered face recognition and management capabilities for building secure identity verification systems. This API enables you to search for faces in collections, index new faces, and manage face databases for duplicate detection and identity matching.

Key Features:

• Face Search: Search for matching faces in your collections
• Face Indexing: Add new faces to collections for future recognition
• Search or Index: Automatically search and index if not found (duplicate detection)
• Face Deletion: Remove faces from collections
• Collection Management: Organize faces into separate collections
• High Accuracy: Advanced AI models with configurable match thresholds
• Regional Deployment: Available in multiple regions for low latency

Search for a face in a specified collection. Returns the face ID if a match is found.

Endpoint: POST /v1/face/search

Request Body:

{
  "image": {
    "bytes": "base64-encoded-image-string",
    "url": null
  },
  "collectionId": "my-collection",
  "faceMatchThreshold": 80
}

Request Parameters:

• image.bytes (string): Base64-encoded JPEG or PNG image
• image.url (string, optional): URL of the image (alternative to bytes)
• collectionId (string, required): The ID of the collection to search against
• faceMatchThreshold (integer, optional): Minimum confidence for face match (0-100, default: 80)
  • 95: FPR 1e-06 (very strict, minimal false positives)
  • 90: FPR 1e-05 (strict)
  • 80: FPR 1e-04 (balanced, default)
  • 70: FPR 1e-03 (lenient)

Response:

{
  "face": {
    "confidence": 0.9987,
    "boundingBox": {
      "x": 120,
      "y": 80,
      "width": 200,
      "height": 250
    }
  },
  "faceId": "face_abc123xyz789",
  "hasFace": true
}

Response Fields:

• face: Detected face information
  • confidence (float): Face detection confidence score [0.0, 1.0]
  • boundingBox: Face location (X, Y, Width, Height in pixels)
• faceId (string, nullable): The ID of the matched face (null if no match found)
• hasFace (boolean): Whether a face was detected in the image

cURL Example:

curl -X POST "https://face-recognition-api-eu.realeyes.ai/v1/face/search" \
  -H "Authorization: ApiKey YWJjMTIzOnh5ejc4OQ==" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "collectionId": "my-collection",
    "faceMatchThreshold": 80
  }'

Index a new face into a specified collection. Returns the generated face ID.

Endpoint: POST /v1/face/index

Request Body:

{
  "image": {
    "bytes": "base64-encoded-image-string",
    "url": null
  },
  "collectionId": "my-collection"
}

Request Parameters:

• image.bytes (string): Base64-encoded JPEG or PNG image
• image.url (string, optional): URL of the image (alternative to bytes)
• collectionId (string, required): The ID of the collection to index the face into

Response:

{
  "face": {
    "confidence": 0.9987,
    "boundingBox": {
      "x": 120,
      "y": 80,
      "width": 200,
      "height": 250
    }
  },
  "faceId": "face_new456def012",
  "hasFace": true
}

Response Fields: Same as Search Face endpoint

cURL Example:

curl -X POST "https://face-recognition-api-eu.realeyes.ai/v1/face/index" \
  -H "Authorization: ApiKey YWJjMTIzOnh5ejc4OQ==" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "collectionId": "my-collection"
  }'

Interactive API documentation is available via Swagger UI:

• EU: https://face-recognition-api-eu.realeyes.ai/swagger
• US: https://face-recognition-api-us.realeyes.ai/swagger

Last updated: 2026-01-27