api/README.md

# Face Swap Video API

FastAPI backend for face swap video processing with MongoDB storage and GPU acceleration.

## Features

- **Source Image Upload**: Upload and store source images in MongoDB
- **Target Video Upload**: Upload and store target videos in MongoDB  
- **Face Swap Processing**: Process face swaps asynchronously with GPU acceleration
- **Result Video Storage**: Store processed result videos with HTTPS download URLs
- **Job Status Tracking**: Monitor processing jobs with real-time status

## 🚀 Docker Deployment (Recommended)

### Prerequisites
- Docker with NVIDIA GPU support (nvidia-docker2)
- NVIDIA GPU with CUDA support

### Quick Start

1. **Build and run with Docker Compose:**
```bash
docker-compose up --build
```

2. **Or build and run with Docker:**
```bash
docker build -t face-swap-api .
docker run --gpus all -p 8000:8000 \
  -e MONGODB_URL="your_mongodb_url" \
  face-swap-api
```

The API will be available at `http://localhost:8000`

## 📡 API Endpoints

### Base URL
```
http://localhost:8000  (Local)
https://your-domain.com/api  (Production)
```

### 1. Source Image Upload
```
POST /api/source-image
Content-Type: multipart/form-data
Body: image file (jpg, png, etc.)
```

**Response:**
```json
{
  "id": "64f7b8c9e1234567890abcde",
  "filename": "source.jpg",
  "file_path": "/path/to/file",
  "uploaded_at": "2024-01-15T10:30:00.000Z",
  "status": "uploaded"
}
```

### 2. Target Video Upload
```
POST /api/target-video
Content-Type: multipart/form-data
Body: video file (mp4, mov, etc.)
```

**Response:**
```json
{
  "id": "64f7b8c9e1234567890abcdf",
  "filename": "target.mp4",
  "file_path": "/path/to/file",
  "uploaded_at": "2024-01-15T10:30:00.000Z",
  "status": "uploaded"
}
```

### 3. Start Face Swap Processing
```
POST /api/face-swap
Content-Type: application/json
Body: {
  "source_image_id": "SOURCE_IMAGE_ID",
  "target_video_id": "TARGET_VIDEO_ID"
}
```

**Response:**
```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "progress": 0.0
}
```

### 4. Get Job Status
```
GET /api/job/{job_id}
```

**Response (when completed):**
```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 100.0,
  "result_video_id": "64f7b8c9e1234567890abce0",
  "result_video_url": "https://your-domain.com/api/result-video/64f7b8c9e1234567890abce0",
  "error": null
}
```

### 5. Download Result Video
```
GET /api/result-video/{result_video_id}
```

Returns the processed video file directly.

### 6. List All Items
```
GET /api/source-images
GET /api/target-videos
GET /api/result-videos
```

### 7. Health Check
```
GET /api/health
GET /
```

## 🐳 Docker Setup

### Dockerfile
The Dockerfile uses:
- **Base Image**: `nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04`
- **GPU Support**: CUDA 12.1 with cuDNN 8
- **Python**: 3.10
- **ONNX Runtime**: GPU version for fast inference

### Environment Variables

```bash
MONGODB_URL=mongodb+srv://...           # MongoDB connection string
BASE_URL=http://localhost:8000          # Base URL for download links
CUDA_VISIBLE_DEVICES=0                   # GPU device ID
```

### Docker Compose

The `docker-compose.yml` includes:
- GPU resource allocation
- Volume mounts for uploads and models
- Automatic restart on failure

## 📝 Usage Examples

### cURL Examples

1. **Upload source image:**
```bash
curl -X POST "http://localhost:8000/api/source-image" \
  -H "accept: application/json" \
  -F "file=@source.jpg"
```

2. **Upload target video:**
```bash
curl -X POST "http://localhost:8000/api/target-video" \
  -H "accept: application/json" \
  -F "file=@target.mp4"
```

3. **Start face swap:**
```bash
curl -X POST "http://localhost:8000/api/face-swap" \
  -H "Content-Type: application/json" \
  -d '{
    "source_image_id": "SOURCE_IMAGE_ID",
    "target_video_id": "TARGET_VIDEO_ID"
  }'
```

4. **Check job status:**
```bash
curl -X GET "http://localhost:8000/api/job/JOB_ID"
```

5. **Download result video:**
```bash
curl -L -o result.mp4 \
  "http://localhost:8000/api/result-video/RESULT_VIDEO_ID"
```

### Python Example

```python
import requests

BASE_URL = "http://localhost:8000"

# 1. Upload source image
with open("source.jpg", "rb") as f:
    response = requests.post(f"{BASE_URL}/api/source-image", files={"file": f})
    source_id = response.json()["id"]

# 2. Upload target video
with open("target.mp4", "rb") as f:
    response = requests.post(f"{BASE_URL}/api/target-video", files={"file": f})
    target_id = response.json()["id"]

# 3. Start face swap
response = requests.post(
    f"{BASE_URL}/api/face-swap",
    json={"source_image_id": source_id, "target_video_id": target_id}
)
job_id = response.json()["job_id"]

# 4. Poll for completion
while True:
    status = requests.get(f"{BASE_URL}/api/job/{job_id}").json()
    if status["status"] == "completed":
        result_url = status["result_video_url"]
        print(f"Download URL: {result_url}")
        break
    time.sleep(5)
```

## 🗄️ Database Schema

### Source Images Collection (`source_images`)
```json
{
  "_id": "ObjectId",
  "filename": "string",
  "file_path": "string",
  "uploaded_at": "datetime",
  "status": "string",
  "content_type": "string",
  "file_size": "number"
}
```

### Target Videos Collection (`target_videos`)
```json
{
  "_id": "ObjectId",
  "filename": "string", 
  "file_path": "string",
  "uploaded_at": "datetime",
  "status": "string",
  "content_type": "string",
  "file_size": "number"
}
```

### Result Videos Collection (`result_videos`)
```json
{
  "_id": "ObjectId",
  "source_image_path": "string",
  "target_video_path": "string", 
  "result_file_path": "string",
  "created_at": "datetime",
  "status": "string",
  "job_id": "string",
  "processing_time": "number"
}
```

### Processing Jobs Collection (`processing_jobs`)
```json
{
  "_id": "ObjectId",
  "job_id": "string (UUID)",
  "source_image_id": "string",
  "target_video_id": "string",
  "status": "string (queued|processing|completed|failed)",
  "created_at": "datetime",
  "progress": "number (0-100)",
  "result_video_id": "string",
  "result_video_url": "string",
  "error": "string"
}
```

## 🔧 Configuration

### MongoDB Connection
- **Connection String**: Set via `MONGODB_URL` environment variable
- **Database**: `face_swap_video`
- **Collections**: `source_images`, `target_videos`, `result_videos`, `processing_jobs`

### GPU Configuration
- **CUDA Version**: 12.1
- **cuDNN**: 8
- **ONNX Runtime**: GPU-enabled
- **Device**: Automatically detects and uses available GPU

## 📊 API Documentation

Once running, visit:
- **Swagger UI**: `http://localhost:8000/docs`
- **ReDoc**: `http://localhost:8000/redoc`

## 🚨 Troubleshooting

### GPU Not Detected
Check NVIDIA drivers:
```bash
nvidia-smi
```

### MongoDB Connection Issues
Verify connection string and network access to MongoDB Atlas.

### Model Download Failures
Ensure `TOKEN` or `HF_TOKEN` environment variable is set for Hugging Face downloads.

## 📦 Files Structure

```
.
├── api_server.py          # Main API server (no Gradio)
├── Dockerfile             # Docker image with GPU support
├── docker-compose.yml     # Docker Compose configuration
├── requirements.txt       # Python dependencies
├── DeepFakeAI/           # Face swap processing library
└── uploads/               # Uploaded files directory
    ├── source_images/
    ├── target_videos/
    └── result_videos/
```