Sebastian Krüger
800edc08ea
FastAPI wrapper around FaceFusion v3.5.3 submodule with: - Sync and async (job-based) processing endpoints - FaceFusion bridge with manual key registration and Lock-serialized processing - Multi-target Dockerfile (CPU + CUDA GPU) - Docker Compose configs for dev, prod-cpu, and prod-gpu - Gitea CI/CD workflow with dual image builds - All 11 FaceFusion processors supported via options API Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
116 lines
3.4 KiB
Markdown
116 lines
3.4 KiB
Markdown
# 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 with CPU and CUDA GPU support.
|
|
|
|
## Features
|
|
|
|
- Synchronous and asynchronous (job-based) processing
|
|
- Face swapping, enhancement, editing, lip sync, age modification, expression restoration, frame enhancement/colorization, background removal
|
|
- Multi-target Docker builds (CPU + CUDA GPU)
|
|
- Model persistence via Docker volumes
|
|
- Gitea CI/CD with dual image publishing
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Build and run (CPU)
|
|
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 (GPU, 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
|
|
|
|
### CPU (VPS)
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml up -d
|
|
```
|
|
|
|
### GPU (NVIDIA)
|
|
|
|
```bash
|
|
docker compose -f docker-compose.gpu.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
|