FLUX Operations

Instructions

Manage FLUX backends within the ITI image generation service at ITI/infrastructure/stable-diffusion/. The service supports three backends: sd (legacy Stable Diffusion), flux-local (FLUX.2 Klein 4B), and flux-api (BFL cloud API).

Setting the default backend:

# In .env (native mode) or docker-compose.yml
SD_DEFAULT_BACKEND=flux-api    # BFL cloud (recommended default)
SD_DEFAULT_BACKEND=flux-local  # Local Klein 4B
SD_DEFAULT_BACKEND=sd          # Legacy Stable Diffusion

Per-request override: include "backend": "flux-api" or "flux-local" in the JSON body.

Starting the service (native — M3 Max with MPS):

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

Starting the service (Docker):

cd ITI/infrastructure/n8n-dify
docker compose --profile sd up -d stable-diffusion

Ensure the docker-compose.yml stable-diffusion service has these environment variables:

environment:
  SD_DEFAULT_BACKEND: ${SD_DEFAULT_BACKEND:-flux-api}
  SD_BFL_API_KEY: ${SD_BFL_API_KEY}
  SD_BFL_DEFAULT_MODEL: ${SD_BFL_DEFAULT_MODEL:-flux-2-pro-preview}
  SD_FLUX_MODEL_ID: ${SD_FLUX_MODEL_ID:-black-forest-labs/FLUX.2-klein-4B}

BFL API credential management:

1. Obtain an API key at https://api.bfl.ai/
2. Store in .env as SD_BFL_API_KEY=bfl_... — NEVER commit this value
3. The .gitignore at ITI/infrastructure/stable-diffusion/.gitignore excludes .env files
4. For Docker, set SD_BFL_API_KEY in ITI/infrastructure/n8n-dify/.env

Health check and backend status:

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

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

# Available models
curl -s http://localhost:7860/api/models | python3 -m json.tool

FLUX Klein local model management:

The Klein 4B model downloads from Hugging Face on first use (~8 GB). Cache location:

Mode	Cache Path
Native	./models/
Docker	sd_models volume

Pre-download to avoid first-request delay:

python3 -c "
from diffusers import Flux2KleinPipeline
Flux2KleinPipeline.from_pretrained(
    'black-forest-labs/FLUX.2-klein-4B',
    cache_dir='./models'
)
print('FLUX Klein 4B downloaded successfully')
"

Requirements: diffusers>=0.37.0, transformers>=4.45.0, sentencepiece.

BFL API model configuration:

Environment Variable	Default	Purpose
SD_BFL_API_KEY	(required)	BFL authentication
SD_BFL_API_BASE	https://api.bfl.ai/v1	API endpoint
SD_BFL_DEFAULT_MODEL	flux-2-pro-preview	Default FLUX model
SD_BFL_POLL_INTERVAL	1.0	Seconds between status polls
SD_BFL_POLL_TIMEOUT	120.0	Max seconds to wait for result

Available BFL models:

Model ID	Quality	Speed	Price/MP
flux-2-pro-preview	Highest (latest)	~5s	$0.03
flux-2-pro	High (fixed snapshot)	~5s	$0.03
flux-2-max	Ultra (grounding search)	~8s	$0.07
flux-2-flex	High (typography)	~6s	$0.06
flux-2-klein-4b	Good (fast)	<1s	$0.014
flux-2-klein-9b-preview	Better (balanced)	~1s	$0.015

FLUX Klein local parameter configuration:

Environment Variable	Default	Purpose
SD_FLUX_MODEL_ID	black-forest-labs/FLUX.2-klein-4B	Hugging Face model ID
SD_FLUX_DEFAULT_STEPS	4	Inference steps (distilled)
SD_FLUX_DEFAULT_GUIDANCE_SCALE	4.0	Guidance scale
SD_FLUX_MAX_IMAGE_SIZE	2048	Max dimension in pixels

Troubleshooting:

Symptom	Diagnosis	Fix
402 Payment Required from BFL	Insufficient API credits	Add credits at https://api.bfl.ai/
401 Unauthorized from BFL	Invalid API key	Verify SD_BFL_API_KEY value
Timeout on BFL generation	Network or model load time	Increase SD_BFL_POLL_TIMEOUT; check BFL status
OOM with FLUX Klein local	Model requires ~13 GB	Use MPS (Apple Silicon) or enable CPU offload
FLUX Klein slow on CPU	GPU required for reasonable speed	Set SD_DEVICE=auto for MPS; use flux-api otherwise
Model download fails	Hugging Face access or network	Set SD_HUGGINGFACE_TOKEN; check connectivity
Port 7860 in use	Previous instance not terminated	`lsof -ti:7860	xargs kill -9` then restart
Flux2KleinPipeline not found	diffusers too old	Upgrade: pip install 'diffusers>=0.37.0'

Disk management:

# Check FLUX model cache
du -sh ./models/models--black-forest-labs--FLUX.2-klein-4B/ 2>/dev/null

# Check outputs
du -sh ./outputs/

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

n8n integration from Docker network:

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

Cost monitoring for BFL API:

Track spend by counting API calls in outputs directory or server logs. Budget estimation:

Volume	Estimated Monthly (Pro)	Estimated Monthly (Klein API)
100 images/month	$3.00	$1.40
1,000 images/month	$30.00	$14.00
10,000 images/month	$300.00	$140.00

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