HistoryFace AI
Upload a selfie, get transformed into your historical twin. The app extracts a 128-dimension facial encoding from your photo, matches it against a database of historical figures using cosine similarity, then runs a face swap through a self-hosted FaceFusion model on HuggingFace Spaces. Includes concurrency throttling, auto-expiring images with Cloudinary cleanup, and a freemium usage gate.
Project Overview
HistoryFace is a full-stack AI web app where users upload a selfie and get transformed into a historical figure. It's a multi-step AI processing pipeline: face detection using dlib, cosine similarity matching against pre-computed historical figure embeddings, then face swapping via a self-hosted FaceFusion model on HuggingFace Spaces.
The Challenge
Creating a viral AI face-swapping app requires complex facial recognition, expensive GPU processing, smart cost management, and a sustainable monetization strategy.
The Solution
Built a complete SaaS integrating HuggingFace AI models with custom facial recognition. Freemium model with session-based usage tracking, Redis-based concurrency throttling (max 2 simultaneous jobs), and automated Cloudinary cleanup that expires generated images after 48 hours.
Technology Stack
Backend
Frontend
Ai_Ml
Integrations
Deployment
Key Features
128-dimension facial encoding with cosine similarity matching against ~65 historical figures
Self-hosted FaceFusion model on HuggingFace Spaces with Gradio API
Redis concurrency control — max 2 simultaneous face-swap jobs, 503 with retry-after if overloaded
Auto-expiring images: 48-hour TTL with background Cloudinary cleanup daemon
Freemium gate: 1 match + 1 randomize per anonymous session, unlimited for logged-in users
Client-side image compression (800x800 max, LANCZOS, JPEG quality 75) before upload
Business Impact
Cost-effective AI model integration without running own GPU infrastructure
Concurrency control prevents HuggingFace endpoint from being overwhelmed
Automated asset cleanup prevents runaway Cloudinary storage costs
Freemium model balances free trials with paid conversion
Technical Achievements
Multiple AI integrations in one project: facial recognition, face swapping, and conversational AI
Smart cost management with concurrency limits and auto-expiring assets
Full SaaS architecture with auth, usage tracking, and payment integration
Production concerns handled: compression, throttling, cleanup, rate limiting
Technical Implementation
Four Django apps: accounts, imagegen, faceswap, chat. The face matching pipeline uses dlib's CNN-based face detector to extract 128-dimensional encodings, then cosine similarity against pre-computed embeddings. The HuggingFace client authenticates with a private Space, calls /setup_facefusion then /process_images with retry logic and exponential backoff. A daemon thread runs every 6 hours to clean up expired Cloudinary assets. Redis cache counters enforce concurrent job limits.