FaceFusion API

REST API wrapping 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

# 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:

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

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