File size: 6,064 Bytes
df4a21a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | ---
title: DeepFake Detector API
emoji: 🎭
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
---
# 🎭 DeepFake Detector API
FastAPI backend for detecting AI-generated (deepfake) images using an ensemble of state-of-the-art deep learning models.
## 🤖 Models
This API uses a fusion ensemble of 5 deep learning models:
- **CNN Transfer** (EfficientNet-B0) - Transfer learning from ImageNet
- **ViT Base** (Vision Transformer) - Attention-based architecture
- **DeiT Distilled** (Data-efficient Image Transformer) - Distilled ViT variant
- **Gradient Field CNN** - Custom architecture analyzing gradient patterns
- **FFT CNN** - Frequency domain analysis using Fast Fourier Transform
All models are combined using a **Logistic Regression stacking ensemble** for optimal accuracy.
## 🔗 API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check - returns API status |
| `/ready` | GET | Model readiness check - confirms models are loaded |
| `/models` | GET | List all loaded models with metadata |
| `/predict` | POST | Predict if an image is real or AI-generated |
| `/docs` | GET | Interactive Swagger API documentation |
| `/redoc` | GET | Alternative API documentation |
## 🚀 Usage Example
### Using cURL
```bash
# Check if API is ready
curl https://lukhsaankumar-deepfakedetectorbackend.hf.space/ready
# Make a prediction
curl -X POST "https://lukhsaankumar-deepfakedetectorbackend.hf.space/predict" \
-F "file=@image.jpg" \
-F "explain=true"
```
### Using Python
```python
import requests
# Upload an image for prediction
url = "https://lukhsaankumar-deepfakedetectorbackend.hf.space/predict"
files = {"file": open("image.jpg", "rb")}
data = {"explain": True}
response = requests.post(url, files=files, data=data)
result = response.json()
print(f"Prediction: {result['prediction']}")
print(f"Confidence: {result['confidence']:.2%}")
print(f"Explanation: {result['explanation']}")
```
## 🎯 Response Format
```json
{
"prediction": "fake",
"confidence": 0.8734,
"probabilities": {
"real": 0.1266,
"fake": 0.8734
},
"model_predictions": {
"cnn_transfer": {"prediction": "fake", "confidence": 0.89},
"vit_base": {"prediction": "fake", "confidence": 0.92},
"deit": {"prediction": "fake", "confidence": 0.85},
"gradient_field": {"prediction": "real", "confidence": 0.55},
"fft_cnn": {"prediction": "fake", "confidence": 0.78}
},
"fusion_confidence": 0.8734,
"explanation": "AI-powered analysis of the prediction...",
"processing_time_ms": 342
}
```
## 🔧 Configuration
### Required Secrets
Set these in your Space Settings → Repository secrets:
| Secret | Description | Required |
|--------|-------------|----------|
| `GOOGLE_API_KEY` | Google Gemini API key for AI explanations | Yes |
| `HF_TOKEN` | Hugging Face token (auto-set by Spaces) | No |
### Optional Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `HF_FUSION_REPO_ID` | `DeepFakeDetector/fusion-logreg-final` | Hugging Face model repository |
| `CORS_ORIGINS` | Multiple defaults | Comma-separated allowed CORS origins |
| `GEMINI_MODEL` | `gemini-2.5-flash` | Gemini model for explanations |
## 🏗️ Architecture
```
┌─────────────┐
│ Client │
└──────┬──────┘
│
▼
┌─────────────────────────────────┐
│ FastAPI Backend │
│ ┌──────────────────────────┐ │
│ │ Model Registry │ │
│ │ ┌────────────────────┐ │ │
│ │ │ CNN Transfer │ │ │
│ │ │ ViT Base │ │ │
│ │ │ DeiT Distilled │ │ │
│ │ │ Gradient Field │ │ │
│ │ │ FFT CNN │ │ │
│ │ └────────────────────┘ │ │
│ │ ┌────────────────────┐ │ │
│ │ │ Fusion Ensemble │ │ │
│ │ │ (LogReg Stacking) │ │ │
│ │ └────────────────────┘ │ │
│ └──────────────────────────┘ │
│ ┌──────────────────────────┐ │
│ │ Gemini Explainer │ │
│ └──────────────────────────┘ │
└─────────────────────────────────┘
```
## 📊 Performance
- **Accuracy**: ~87% on test set (OpenFake dataset)
- **Inference Time**: ~200-500ms per image (with GPU)
- **Model Size**: ~500MB total
- **Supported Formats**: JPG, PNG, WEBP
## 🐛 Troubleshooting
### Models not loading?
- Check the Logs tab for specific errors
- Verify `HF_FUSION_REPO_ID` points to a valid repository
- Ensure the repository is public or `HF_TOKEN` is set
### Explanations not working?
- Verify `GOOGLE_API_KEY` is set in Space Settings
- Check if you have Gemini API quota remaining
- Review logs for API errors
### CORS errors?
- Add your frontend domain to `CORS_ORIGINS` in Space Settings
- Format: `https://yourdomain.com,https://www.yourdomain.com`
## 📚 Documentation
- **Interactive Docs**: Visit `/docs` for Swagger UI
- **ReDoc**: Visit `/redoc` for alternative documentation
- **Source Code**: [GitHub Repository](https://github.com/lukhsaankumar/DeepFakeDetector)
## 📝 License
This project is part of the MacAI Society research initiative.
## 🙏 Acknowledgments
- Models trained on OpenFake, ImageNet, and custom datasets
- Powered by PyTorch, Hugging Face, and FastAPI
- AI explanations by Google Gemini
---
**Built with ❤️ by MacAI Society**
|