Image Generation Service Operations

Instructions

Operate the ITI multi-backend image generation service at ITI/infrastructure/stable-diffusion/. The service exposes a unified FastAPI interface on port 7860 with three backends:

Backend	ID	Engine
Stable Diffusion	sd	Local diffusers pipeline
FLUX Klein 4B	flux-local	Local diffusers FLUX pipeline
BFL FLUX API	flux-api	Cloud API (api.bfl.ai)

For FLUX-specific configuration (BFL API credentials, Klein model downloads, FLUX model selection), see the flux-operations skill.

Starting the service (native — recommended for M3 Max):

cd ITI/infrastructure/stable-diffusion
source .venv/bin/activate
SD_DEVICE=auto SD_MODEL_DIR=./models SD_OUTPUT_DIR=./outputs \
  SD_DEFAULT_BACKEND=flux-api \
  SD_BFL_API_KEY=<your-key> \
  uvicorn app.main:app --host 0.0.0.0 --port 7860

Native mode uses Metal Performance Shaders (MPS) on Apple Silicon for 10-15x faster generation than Docker CPU mode.

Starting the service (Docker):

cd ITI/infrastructure/n8n-dify

# Start alongside the main stack
docker compose --profile sd up -d stable-diffusion

# Check status
docker compose --profile sd ps

# View logs
docker compose logs -f iti-image-generation

Health check:

# Full health (all backends)
curl -s http://localhost:7860/health | python3 -m json.tool

# Backend availability
curl -s http://localhost:7860/api/backends | python3 -m json.tool

# Service info
curl -s http://localhost:7860/info | python3 -m json.tool

Backend switching:

Set the default in .env:

SD_DEFAULT_BACKEND=flux-api   # BFL cloud (recommended)
SD_DEFAULT_BACKEND=flux-local # Local FLUX Klein 4B
SD_DEFAULT_BACKEND=sd         # Legacy Stable Diffusion

Or override per-request by including "backend": "flux-api" in the JSON body.

Model management:

Models cache in sd_models Docker volume or ./models/ (native). First startup downloads from Hugging Face.

# Switch SD model
SD_MODEL_ID=stabilityai/stable-diffusion-xl-base-1.0

# Restart to load
docker compose --profile sd restart stable-diffusion

Cleanup and disk management:

# Check model cache
du -sh ./models/

# Check outputs
du -sh ./outputs/

# Prune old outputs (keep last 7 days)
find ./outputs -name "*.png" -mtime +7 -delete

# Docker volume sizes
docker system df -v | grep sd_

Troubleshooting:

Symptom	Diagnosis	Fix
OOM during generation	Image too large or model too big	Reduce dimensions; use flux-api instead
Slow in Docker	CPU mode overhead	Switch to native MPS mode
Model download hangs	Network or HF rate limit	Set SD_HUGGINGFACE_TOKEN; check network
Black images on MPS	PyTorch MPS float16 bug	Ensure SD_DEVICE=auto
Service unhealthy	Model still loading	Allow 60-120s for first load
Port 7860 in use	Previous instance	`lsof -ti:7860	xargs kill -9`
BFL 402 error	No API credits	Add credits at https://api.bfl.ai/

Resource monitoring:

# Docker mode
docker stats iti-image-generation --no-stream

# Native mode
vm_stat | head -5

Backend	Idle Memory	Active Memory	Speed (1024×1024)
SD 2.1	~500 MB	~5 GB	8-12s (MPS)
FLUX Klein local	~500 MB	~13 GB	5-15s (MPS)
FLUX API	Negligible	Negligible	2-10s (network)

n8n integration:

Service Mode	n8n URL
Docker (same network)	http://stable-diffusion:7860/api/txt2img
Native (outside Docker)	http://host.docker.internal:7860/api/txt2img

Security:

• Set SD_API_KEY in production to require authentication via X-API-Key header
• SD safety checker prevents NSFW content by default
• Output path traversal is validated against the output directory
• BFL API key is stored in .env files only (gitignored)

Backup considerations:

• Model cache: no backup needed — re-downloadable
• Generated outputs: back up if needed for retention
• Configuration: tracked in docker-compose.yml and .env.example
• BFL API key: store securely; not recoverable if lost

Key file paths:

Path	Contents
ITI/infrastructure/stable-diffusion/app/config.py	Backend enum, all settings
ITI/infrastructure/stable-diffusion/app/pipeline.py	Multi-backend dispatch logic
ITI/infrastructure/stable-diffusion/app/main.py	FastAPI endpoints
ITI/infrastructure/stable-diffusion/.env.example	Configuration template
ITI/infrastructure/stable-diffusion/.env	Local credentials (gitignored)
ITI/infrastructure/n8n-dify/docker-compose.yml	Docker service definition

Related skills:

• flux-operations — FLUX-specific backend configuration, BFL credentials, Klein model setup
• flux-image-generation — FLUX prompt engineering and model selection
• stable-diffusion-image-generation — SD-specific prompt engineering and parameters