managarten/services/mana-image-gen/CLAUDE.md

mana-image-gen

AI image generation microservice using FLUX models via HuggingFace diffusers on NVIDIA CUDA. Lives on the Windows GPU server (mana-server-gpu, RTX 3090).

⚠️ Earlier history: this directory used to contain a Mac Mini–only implementation built on flux2.c (MPS, Apple Silicon arm64). That version was removed when the service moved fully onto the Windows GPU. If you're looking for the old code, see git history before this commit.

Tech Stack

Layer	Technology
Runtime	Python 3.11 + uvicorn (Windows)
Framework	FastAPI
Inference	HuggingFace diffusers + PyTorch CUDA
Default model	FLUX.1-schnell (BFL, Apache 2.0, 4-step distilled)
GPU	NVIDIA RTX 3090 (24 GB VRAM)
Auth	GPU_API_KEY middleware (app/api_auth.py)
Process supervision	Windows Scheduled Task ManaImageGen (AtLogOn)

Port: 3023

Where it runs

Host	Path on disk	Entrypoint
Windows GPU server (192.168.178.11)	C:\mana\services\mana-image-gen\	service.pyw via Scheduled Task ManaImageGen

The service is exposed publicly via Cloudflare Tunnel + the Mac Mini TCP-proxy (gpu-proxy.py):

Internet → Cloudflare → Mac Mini (gpu-proxy.py) → 192.168.178.11:3023

Public URL: https://gpu-img.mana.how

Quick Start (Windows GPU)

# As tills on mana-server-gpu
cd C:\mana\services\mana-image-gen
C:\mana\venvs\image-gen\Scripts\python.exe service.pyw

# Or kick the scheduled task
Start-ScheduledTask -TaskName "ManaImageGen"

# Health
curl http://localhost:3023/health

The Scheduled Task runs:

Execute:    C:\mana\venvs\image-gen\Scripts\python.exe
Arguments:  C:\mana\services\mana-image-gen\service.pyw
WorkingDir: C:\mana\services\mana-image-gen

API Endpoints

Method	Path	Description
GET	/health	Liveness + GPU + model status
GET	/models	Loaded model info
POST	/generate	Generate an image (returns {image_url, ...})
GET	/images/{filename}	Serve a generated image
DELETE	/images/{filename}	Delete a generated image
POST	/cleanup?max_age_hours=24	Sweep old images

All non-health endpoints are gated by ApiKeyMiddleware — clients must send Authorization: Bearer $GPU_API_KEY (header name and verification details in app/api_auth.py).

Generate request

{
  "prompt": "A futuristic city skyline at sunset",
  "width": 1024,
  "height": 1024,
  "steps": 4,
  "seed": -1
}

Code layout

services/mana-image-gen/
├── app/
│   ├── __init__.py
│   ├── main.py            # FastAPI endpoints
│   ├── flux_service.py    # diffusers pipeline + generate_image()
│   ├── api_auth.py        # ApiKeyMiddleware (GPU_API_KEY)
│   └── vram_manager.py    # shared VRAM accounting helper
└── service.pyw            # Windows runner (used by Scheduled Task)

Configuration (.env on the Windows GPU box)

PORT=3023
IMAGE_MODEL_ID=black-forest-labs/FLUX.1-schnell
DEFAULT_STEPS=4
DEFAULT_WIDTH=1024
DEFAULT_HEIGHT=1024
MAX_STEPS=8
GUIDANCE_SCALE=0.0
GENERATION_TIMEOUT=120
OUTPUT_DIR=C:\mana\services\mana-image-gen\outputs
CORS_ORIGINS=https://mana.how,https://chat.mana.how
GPU_API_KEY=...                # cross-service auth, also used by mana-llm

The service.pyw runner loads .env from the service directory before starting uvicorn.

Operations

# Status
Get-ScheduledTask -TaskName "ManaImageGen" | Format-List TaskName, State
Get-NetTCPConnection -LocalPort 3023 -State Listen

# Restart
Stop-ScheduledTask -TaskName "ManaImageGen"
Start-ScheduledTask -TaskName "ManaImageGen"

# Logs
Get-Content C:\mana\services\mana-image-gen\service.log -Tail 50

Model details

Field	Value
Model	black-forest-labs/FLUX.1-schnell
Parameters	~12B
License	Apache 2.0 (commercial use OK)
Weights size	~24 GB on disk
VRAM footprint	~12 GB (with the default precision/optimization settings)
Optimal sampling steps	4 (distilled "schnell" variant)
HuggingFace gate	Requires HF login + license accept

Reference

• docs/WINDOWS_GPU_SERVER_SETUP.md — full Windows GPU box setup, all AI services, scheduled task setup, firewall rules, Cloudflare tunnel
• docs/PORT_SCHEMA.md — port assignments across services