facefusion-api/README.md

# FaceFusion API

REST API wrapping [FaceFusion](https://github.com/facefusion/facefusion) v3.5.3 for face swapping, enhancement, lip sync, and other face/frame processing. Containerized for CPU-only execution.

## Features

- Synchronous and asynchronous (job-based) processing
- Face swapping, enhancement, editing, lip sync, age modification, expression restoration, frame enhancement/colorization, background removal
- Dockerized for easy deployment
- Model persistence via Docker volumes
- Gitea CI/CD automated builds

## Quick Start

```bash
# Build and run
docker compose build
docker compose up -d

# Download models
curl -X POST http://localhost:8000/api/v1/models/download \
  -H 'Content-Type: application/json' \
  -d '["face_swapper"]'

# Face swap (synchronous)
curl -X POST http://localhost:8000/api/v1/process \
  -F source=@source.jpg \
  -F target=@target.jpg \
  -o result.jpg

# Face swap (async job)
curl -X POST http://localhost:8000/api/v1/jobs \
  -F source=@source.jpg \
  -F target=@target.jpg

# Check job status
curl http://localhost:8000/api/v1/jobs/{job_id}

# Download result
curl http://localhost:8000/api/v1/jobs/{job_id}/result -o result.jpg
```

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/v1/process` | Synchronous processing (returns file) |
| `POST` | `/api/v1/jobs` | Create async job |
| `GET` | `/api/v1/jobs/{id}` | Job status |
| `GET` | `/api/v1/jobs/{id}/result` | Download result |
| `DELETE` | `/api/v1/jobs/{id}` | Cancel/delete job |
| `GET` | `/api/v1/processors` | List available processors |
| `GET` | `/api/v1/models` | List downloaded models |
| `POST` | `/api/v1/models/download` | Trigger model download |
| `GET` | `/api/v1/health` | Health check |
| `GET` | `/api/v1/system` | System info (CPU, memory) |

## Processing Options

Pass options as a JSON string in the `options` form field:

```json
{
  "processors": ["face_swapper", "face_enhancer"],
  "face_swapper": {
    "model": "hyperswap_1a_256",
    "weight": 0.5
  },
  "face_enhancer": {
    "model": "gfpgan_1.4",
    "blend": 80
  },
  "output": {
    "image_quality": 90
  }
}
```

Available processors: `face_swapper`, `face_enhancer`, `face_editor`, `lip_syncer`, `age_modifier`, `expression_restorer`, `frame_enhancer`, `frame_colorizer`, `background_remover`, `deep_swapper`, `face_debugger`.

## Deployment

```bash
docker compose -f docker-compose.prod.yml up -d
```

## Configuration

Environment variables (prefix `FF_`):

| Variable | Default | Description |
|----------|---------|-------------|
| `FF_EXECUTION_PROVIDERS` | `["cpu"]` | ONNX execution providers |
| `FF_EXECUTION_THREAD_COUNT` | `4` | Processing threads |
| `FF_VIDEO_MEMORY_STRATEGY` | `moderate` | `strict` / `moderate` / `tolerant` |
| `FF_MODELS_DIR` | `/data/models` | Model storage path |
| `FF_MAX_UPLOAD_SIZE_MB` | `500` | Upload size limit |
| `FF_SYNC_TIMEOUT_SECONDS` | `120` | Sync processing timeout |
| `FF_LOG_LEVEL` | `info` | Log level |

## Architecture

- **FastAPI** with single uvicorn worker (required - FaceFusion uses global mutable state)
- **FaceFusion** included as git submodule, pinned to v3.5.3
- All processing serialized through `threading.Lock`
- Background job queue with daemon worker thread
- Models persisted in Docker volume, not baked into image