realesrgan-api/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Overview

This is the Real-ESRGAN API project - a sophisticated, full-featured REST API for image upscaling using Real-ESRGAN. The API supports both synchronous and asynchronous (job-based) processing with Docker containerization for CPU and GPU deployments.

Architecture

Core Components

• app/main.py: FastAPI application with lifecycle management
• app/routers/: API endpoint handlers
  • upscale.py: Synchronous and async upscaling endpoints
  • models.py: Model management endpoints
  • health.py: Health checks and system monitoring
• app/services/: Business logic
  • realesrgan_bridge.py: Real-ESRGAN model loading and inference
  • file_manager.py: File handling and directory management
  • worker.py: Async job queue with thread pool
  • model_manager.py: Model downloading and metadata
• app/schemas/: Pydantic request/response models

Data Directories

• /data/uploads: User uploaded files
• /data/outputs: Processed output images
• /data/models: Real-ESRGAN model weights (.pth files)
• /data/temp: Temporary processing files
• /data/jobs: Async job metadata and status

Development Workflow

Local Setup (CPU)

# Install dependencies
pip install -r requirements.txt -r requirements-cpu.txt

# Run development server
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Access API
# Swagger: http://localhost:8000/docs
# ReDoc: http://localhost:8000/redoc

Docker Development

# Build CPU image
docker compose build

# Run container
docker compose up -d

# View logs
docker compose logs -f api

# Stop container
docker compose down

GPU Development

# Build GPU image
docker compose -f docker-compose.gpu.yml build

# Run with GPU
docker compose -f docker-compose.gpu.yml up -d

# Check GPU usage
docker compose -f docker-compose.gpu.yml exec api nvidia-smi

Configuration

Environment Variables (prefix: RSR_)

All settings from app/config.py can be configured via environment:

RSR_UPLOAD_DIR=/data/uploads
RSR_OUTPUT_DIR=/data/outputs
RSR_MODELS_DIR=/data/models
RSR_EXECUTION_PROVIDERS=["cpu"]  # or ["cuda"] for GPU
RSR_TILE_SIZE=400               # Tile size for large images
RSR_MAX_UPLOAD_SIZE_MB=500
RSR_SYNC_TIMEOUT_SECONDS=300

Docker Compose Environment

Set in docker-compose.yml or docker-compose.gpu.yml environment section.

API Endpoints

Key Endpoints

• POST /api/v1/upscale: Synchronous upscaling (direct response)
• POST /api/v1/jobs: Create async upscaling job
• GET /api/v1/jobs/{job_id}: Check job status
• GET /api/v1/jobs/{job_id}/result: Download result
• GET /api/v1/models: List available models
• POST /api/v1/models/download: Download models
• GET /api/v1/health: Health check
• GET /api/v1/system: System information

Model Management

Available Models

'RealESRGAN_x2plus'          # 2x upscaling
'RealESRGAN_x3plus'          # 3x upscaling
'RealESRGAN_x4plus'          # 4x general purpose (default)
'RealESRGAN_x4plus_anime_6B' # 4x anime/art (lighter)

Downloading Models

# Download specific model
curl -X POST http://localhost:8000/api/v1/models/download \
  -H 'Content-Type: application/json' \
  -d '{"models": ["RealESRGAN_x4plus"]}'

# List available models
curl http://localhost:8000/api/v1/models

Async Job Processing

Workflow

1. Submit image → POST /api/v1/jobs → returns job_id
2. Poll status → GET /api/v1/jobs/{job_id}
3. When status=completed → GET /api/v1/jobs/{job_id}/result

Job States

• queued: Waiting in queue
• processing: Currently being processed
• completed: Successfully processed
• failed: Processing failed

Integration with facefusion-api

This project follows similar patterns to facefusion-api:

• File Management: Same file_manager.py utilities
• Worker Queue: Similar async job processing architecture
• Docker Setup: Multi-variant CPU/GPU builds
• Configuration: Environment-based settings with pydantic
• Gitea CI/CD: Automatic Docker image building
• API Structure: Organized routers and services

Development Tips

Adding New Endpoints

1. Create handler in app/routers/{domain}.py
2. Define request/response schemas in app/schemas/{domain}.py
3. Include router in app/main.py: app.include_router(router)

Adding Services

1. Create service module in app/services/{service}.py
2. Import and use in routers

Testing

Run a quick test:

# Check API is running
curl http://localhost:8000/

# Check health
curl http://localhost:8000/api/v1/health

# Check system info
curl http://localhost:8000/api/v1/system

Troubleshooting

Models Not Loading

# Check if models directory exists and has permission
ls -la /data/models/

# Download models manually
curl -X POST http://localhost:8000/api/v1/models/download \
  -H 'Content-Type: application/json' \
  -d '{"models": ["RealESRGAN_x4plus"]}'

GPU Not Detected

# Check GPU availability
docker compose -f docker-compose.gpu.yml exec api python -c "import torch; print(torch.cuda.is_available())"

# Check system GPU
nvidia-smi

Permission Issues with Volumes

# Fix volume ownership
docker compose exec api chown -R 1000:1000 /data/

Git Workflow

The project uses Gitea as the remote repository:

# Add remote
git remote add gitea <gitea-repo-url>

# Commit and push
git add .
git commit -m "Add feature"
git push gitea main

Gitea workflows automatically:

• Build Docker images (CPU and GPU)
• Run tests
• Publish to Container Registry

Important Notes

• Model Weights: Downloaded from GitHub releases (~100MB each)
• GPU Support: Requires NVIDIA Docker runtime
• Async Processing: Uses thread pool (configurable workers)
• Tile Processing: Handles large images by splitting into tiles
• Data Persistence: Volumes recommended for production