# Face API A production-ready RESTful API wrapper for [DeepFace](https://github.com/serengil/deepface) - providing face verification, recognition, analysis, and embedding generation capabilities. ## Features - **Face Verification**: Compare two face images to determine if they belong to the same person - **Face Analysis**: Analyze facial attributes (age, gender, race, emotion) - **Face Embeddings**: Generate face embeddings for similarity comparisons - **Face Recognition**: Match faces against a database of stored embeddings - **API Key Authentication**: Secure endpoints with header-based API key - **SQLite Database**: Store face embeddings and verification logs - **Type Safety**: Full Pydantic validation for requests and responses - **Auto Documentation**: Interactive OpenAPI/Swagger docs ## Tech Stack - **FastAPI**: Modern, high-performance web framework - **DeepFace**: State-of-the-art face recognition library - **SQLModel**: SQL database ORM with Pydantic integration - **Pydantic**: Data validation and settings management - **SQLite**: Lightweight embedded database ## Installation 1. Clone the repository: ```bash git clone cd face-api ``` 2. Create and activate a virtual environment: ```bash python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate ``` 3. Install dependencies: ```bash pip install -e . ``` 4. Create environment file: ```bash cp .env.example .env ``` 5. Edit `.env` and set your API key: ```env API_KEY=your-secret-api-key-here ``` ## Running the API ### Development Mode ```bash face-api ``` The API will be available at: - **API**: http://localhost:8000 - **Interactive Docs**: http://localhost:8000/docs - **ReDoc**: http://localhost:8000/redoc ### Production Mode ```bash uvicorn face_api.main:app --host 0.0.0.0 --port 8000 ``` ## API Endpoints All endpoints require the `X-API-Key` header for authentication. ### Health Check ```bash GET / GET /health ``` ### Face Verification Compare two face images: ```bash POST /api/v1/verify ``` **Request Body:** ```json { "img1": "base64_encoded_image_or_path", "img2": "base64_encoded_image_or_path", "model_name": "VGG-Face", "detector_backend": "opencv", "distance_metric": "cosine", "enforce_detection": true } ``` ### Face Analysis Analyze facial attributes: ```bash POST /api/v1/analyze ``` **Request Body:** ```json { "img": "base64_encoded_image_or_path", "actions": ["age", "gender", "race", "emotion"], "detector_backend": "opencv", "enforce_detection": true } ``` ### Face Embedding Generate face embedding: ```bash POST /api/v1/embed ``` **Request Body:** ```json { "img": "base64_encoded_image_or_path", "model_name": "VGG-Face", "detector_backend": "opencv", "enforce_detection": true } ``` ### Store Face Embedding Store a face embedding in the database: ```bash POST /api/v1/embed/store ``` **Request Body:** ```json { "person_id": "john_doe_001", "img": "base64_encoded_image_or_path", "metadata": { "name": "John Doe", "department": "Engineering" }, "model_name": "VGG-Face", "detector_backend": "opencv" } ``` ### Face Recognition Recognize a face from the database: ```bash POST /api/v1/recognize ``` **Request Body:** ```json { "img": "base64_encoded_image_or_path", "person_id": null, "threshold": 0.4, "model_name": "VGG-Face", "detector_backend": "opencv" } ``` ## Configuration Configuration is managed via environment variables in `.env`: | Variable | Description | Default | |----------|-------------|---------| | `API_KEY` | API authentication key | Required | | `DATABASE_URL` | SQLite database URL | `sqlite:///./face_api.db` | | `FACE_DETECTOR_BACKEND` | Face detector | `opencv` | | `FACE_RECOGNITION_MODEL` | Recognition model | `VGG-Face` | | `DISTANCE_METRIC` | Distance metric | `cosine` | | `ENABLE_FACE_ALIGNMENT` | Face alignment | `true` | | `APP_NAME` | Application name | `Face API` | | `APP_VERSION` | Application version | `1.0.0` | | `DEBUG` | Debug mode | `false` | ### Available Models **Face Recognition Models:** - VGG-Face - Facenet - Facenet512 - OpenFace - DeepFace - DeepID - ArcFace - Dlib - SFace - GhostFaceNet **Detector Backends:** - opencv - ssd - dlib - mtcnn - retinaface - mediapipe - yolov8 - yunet - centerface **Distance Metrics:** - cosine - euclidean - euclidean_l2 ## Example Usage ### Using cURL ```bash # Verify two faces curl -X POST "http://localhost:8000/api/v1/verify" \ -H "X-API-Key: your-secret-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "img1": "/path/to/image1.jpg", "img2": "/path/to/image2.jpg" }' # Analyze a face curl -X POST "http://localhost:8000/api/v1/analyze" \ -H "X-API-Key: your-secret-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "img": "/path/to/image.jpg", "actions": ["age", "gender", "emotion"] }' ``` ### Using Python ```python import requests import base64 API_URL = "http://localhost:8000" API_KEY = "your-secret-api-key-here" headers = { "X-API-Key": API_KEY, "Content-Type": "application/json" } # Verify faces response = requests.post( f"{API_URL}/api/v1/verify", headers=headers, json={ "img1": "/path/to/image1.jpg", "img2": "/path/to/image2.jpg" } ) print(response.json()) # Store a face response = requests.post( f"{API_URL}/api/v1/embed/store", headers=headers, json={ "person_id": "john_doe", "img": "/path/to/john.jpg", "metadata": {"name": "John Doe"} } ) print(response.json()) # Recognize a face response = requests.post( f"{API_URL}/api/v1/recognize", headers=headers, json={ "img": "/path/to/unknown.jpg" } ) print(response.json()) ``` ## Project Structure ``` face-api/ � src/ � � face_api/ � � __init__.py # Package initialization � � main.py # FastAPI app setup � � config.py # Settings configuration � � database.py # Database setup � � models/ � � � __init__.py � � � face.py # Database models � � � schemas.py # Pydantic schemas � � api/ � � � __init__.py � � � dependencies.py # Auth dependencies � � � routes/ � � � __init__.py � � � verify.py # Verification endpoint � � � analyze.py # Analysis endpoint � � � embed.py # Embedding endpoint � � � recognize.py # Recognition endpoint � � services/ � � __init__.py � � deepface_service.py # DeepFace wrapper � .env.example # Example environment file � .gitignore � pyproject.toml � README.md ``` ## License MIT ## Contributing Contributions are welcome! Please open an issue or submit a pull request. ## Support For issues and questions, please open an issue on the repository.