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:

docker-compose up --build

2. Or build and run with Docker:

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:

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

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

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

4. Get Job Status

GET /api/job/{job_id}

Response (when completed):

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

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:

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

2. Upload target video:

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

3. Start face swap:

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:

curl -X GET "http://localhost:8000/api/job/JOB_ID"

5. Download result video:

curl -L -o result.mp4 \
  "http://localhost:8000/api/result-video/RESULT_VIDEO_ID"

Python Example

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)

{
  "_id": "ObjectId",
  "filename": "string",
  "file_path": "string",
  "uploaded_at": "datetime",
  "status": "string",
  "content_type": "string",
  "file_size": "number"
}

Target Videos Collection (target_videos)

{
  "_id": "ObjectId",
  "filename": "string", 
  "file_path": "string",
  "uploaded_at": "datetime",
  "status": "string",
  "content_type": "string",
  "file_size": "number"
}

Result Videos Collection (result_videos)

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

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

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/