🎭 Facial Liveness API

A real-time face liveness detection API with AWS Rekognition-style challenge/response verification. Prevents spoofing attacks using static photos, videos, or 3D masks by verifying the user is a live human being.

---

🌟 Features

• ✅ Liveness Detection — Distinguish real faces from photos/videos/masks
• 🎯 Challenge-Response — Dynamic gesture challenges (blink, turn, smile)
• ⚡ High Performance — Optimized for real-time processing
• 🔒 Spoof Prevention — Resistant to print attacks, replay attacks, and 3D masks
• 🖥️ REST API — Clean, documented endpoints compatible with any frontend
• ☁️ AWS Integration — Optional AWS Rekognition backend support

---

🏗️ Architecture

Client App  ──HTTP──▶  FastAPI Server
                         │
                    Liveness Engine
                         │
                  OpenCV / AWS Rekognition

---

🛠️ Tech Stack

Layer	Technology
API Framework	FastAPI (Python)
Computer Vision	OpenCV
Face Analysis	AWS Rekognition / Dlib
Challenge Engine	Custom gesture detection
Deployment	Uvicorn / Docker-ready

---

📦 Installation

git clone https://github.com/asad4230/facial-liveness-api.git
cd facial-liveness-api
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

---

🚀 Running the API

uvicorn main:app --reload --host 0.0.0.0 --port 8000

API docs: http://localhost:8000/docs

---

📡 API Endpoints

Method	Endpoint	Description
POST	/api/v1/liveness/check	Submit a frame for liveness verification
POST	/api/v1/liveness/session	Start a new liveness session
GET	/api/v1/liveness/challenge	Get current challenge
GET	/api/v1/health	Health check

---

🔐 Use Cases

• KYC verification in fintech apps
• Secure login with face + liveness factor
• Attendance systems with anti-spoofing
• Identity verification portals

---

📄 License

MIT License

---

Built by [Asad Mushtaq](https://github.com/asad4230) · Solution Architect & Tech Lead