README.md

metadata

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

# 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

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

{
  "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

📝 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