CLAUDE.md

Overview

FaceFusion API - A Python REST API wrapping FaceFusion v3.5.3 for face swapping, enhancement, lip sync, and other face/frame processing. Containerized for CPU-only execution, deployed via Gitea CI/CD at dev.pivoine.art.

Architecture

FastAPI async web framework with single uvicorn worker (mandatory due to FaceFusion's global state)
FaceFusion included as git submodule at facefusion/ pinned to tag 3.5.3
All FaceFusion processing serialized through threading.Lock in facefusion_bridge.py
Background job queue in worker.py for async processing

Key Integration Points

FaceFusion uses global mutable state (state_manager) and module-level ONNX inference pools. The bridge (app/services/facefusion_bridge.py) replicates the initialization side-effects of program.py:

Registers all job_keys and step_keys in job_store
Initializes state defaults via state_manager.init_item()
Initializes job filesystem via job_manager.init_jobs()
Symlinks facefusion/.assets/models/ -> /data/models/ for model persistence

Project Structure

app/
  main.py              # FastAPI app, lifespan, sys.path setup
  config.py            # Pydantic BaseSettings (FF_ env prefix)
  routers/             # API endpoint handlers
  schemas/             # Pydantic request/response models
  services/
    facefusion_bridge.py  # Core FaceFusion integration
    worker.py             # Background job queue
    file_manager.py       # File upload/output handling

Common Commands

# Development
docker compose build
docker compose up

# Production (CPU VPS)
docker compose -f docker-compose.prod.yml up -d

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

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

API Endpoints

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 processors
GET /api/v1/models - List downloaded models
POST /api/v1/models/download - Download models
GET /api/v1/health - Health check
GET /api/v1/system - System info (CPU, memory)

Docker

Base image: python:3.12-slim + onnxruntime
Models persisted in /data/models Docker volume (not baked into image)
Single worker mandatory (--workers 1)

Environment Variables

All prefixed with FF_:

FF_EXECUTION_PROVIDERS - JSON array, e.g. ["cpu"]
FF_EXECUTION_THREAD_COUNT - Default 4
FF_VIDEO_MEMORY_STRATEGY - strict/moderate/tolerant
FF_MODELS_DIR - Model storage path
FF_MAX_UPLOAD_SIZE_MB - Upload limit (default 500)

Important Notes

Never run with multiple uvicorn workers - FaceFusion global state will corrupt
Models are 100MB-1GB each; pre-download via /api/v1/models/download before processing
The facefusion/ submodule should not be modified directly if possible - use symlinks for model paths
Git operations: always push with the valknarthing ssh key

3.3 KiB Raw Blame History