README_HF.md

---
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**