📸 Headshot Pro

AI Professional Headshot Generator

Upload your selfies. Get 40+ studio-quality professional headshots in minutes.

🚀 Live Demo · 📖 Documentation · 🐛 Report Bug · ✨ Request Feature

---

✨ Features

• 🎯 5 Professional Styles — Corporate, LinkedIn Optimized, Creative, Casual, and Academic
• 📸 40+ Headshots — Multiple aspect ratios and background styles per look
• 🆓 Free Tier — Try it free with 3 watermarked preview headshots
• 💎 Crypto Payments — Pay with ETH for instant full-resolution access
• ⬇️ ZIP Download — Download all headshots at once in full resolution
• 🔒 Smart Watermarking — Free previews with watermark, full HD after payment
• 📱 Responsive Design — Beautiful dark theme that works on all devices
• ⚡ Fast Generation — Powered by FAL.ai queue-based API for reliable results

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• A FAL.ai API key

1. Clone the Repository

git clone https://github.com/Hamoun-IA/headshot-pro.git
cd headshot-pro

2. Install Dependencies

pip install fastapi uvicorn httpx aiofiles pillow fal-client qrcode python-multipart

3. Set Your API Key

export FAL_KEY="your-fal-api-key-here"

4. Run the Server

cd backend
uvicorn main:app --host 0.0.0.0 --port 8897

Then open http://localhost:8897 in your browser.

Docker (Optional)

docker-compose up -d

---

📡 API Endpoints

Core

• POST /api/upload — Upload selfie images (max 10, 10MB each)
• POST /api/generate — Start AI headshot generation
• GET /api/status/{session_id} — Poll generation progress
• GET /api/gallery/{session_id} — Get all generated headshots
• GET /api/image/{session_id}/{style}/{filename} — Serve a headshot image

Downloads

• GET /api/download/{session_id} — Download all headshots as ZIP (paid only)
• POST /api/download/{session_id}/single — Download a single headshot

Crypto Payments

• POST /api/crypto/generate-address — Create a payment request (ETH)
• GET /api/crypto/status/{payment_id} — Check payment status
• POST /api/crypto/webhook — Webhook to confirm payment (X-Webhook-Key header)
• GET /api/crypto/qrcode/{payment_id} — Get QR code for payment

Other

• GET /api/health — Health check
• POST /api/waitlist — Join the waitlist
• POST /api/analytics/event — Track analytics events

---

💰 Pricing

• Free — 3 watermarked, low-resolution preview headshots. No credit card needed.
• Pro (€15) — 40+ full-resolution, watermark-free headshots in all 5 styles. Commercial usage rights included. Pay with ETH.

---

🛠️ Tech Stack

• Backend: FastAPI (Python 3.11+)
• Frontend: Vanilla HTML/CSS/JavaScript (no framework)
• AI Engine: FAL.ai — fal-ai/image-apps-v2/headshot-photo & fal-ai/image-editing/professional-photo
• Database: SQLite with WAL mode
• Payments: Ethereum (ETH) with CoinGecko price feeds
• Deployment: Systemd service or Docker

---

📁 Project Structure

headshot-pro/
├── backend/
│   └── main.py            # FastAPI application (all API endpoints + AI logic)
├── frontend/
│   ├── index.html          # Landing page
│   ├── app.html            # Main app (upload, generate, gallery)
│   ├── style.css           # Dark theme styling
│   └── favicon.svg         # Camera icon favicon
├── headshot-pro.service    # Systemd service file (reference)
├── docker-compose.yml      # Docker deployment
├── .env.example            # Environment variables template
├── .gitignore
├── LICENSE
└── README.md

---

⚙️ Environment Variables

Variable	Description	Required
FAL_KEY	Your FAL.ai API key	✅ Yes
CRYPTO_WALLET_ETH	Ethereum wallet address for payments	Optional
CRYPTO_WEBHOOK_KEY	Secret key for payment webhook	Optional

Copy .env.example to .env and fill in your values:

cp .env.example .env

---

🤝 Contributing

Contributions are welcome! Feel free to:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Made with 📸 by Hamoun IA

🌐 Live Demo · 🐙 GitHub