Real-ESRGAN API

REST API wrapping Real-ESRGAN for image upscaling. Features synchronous and asynchronous (job-based) processing with Docker containerization.

Features

• Synchronous Upscaling: Direct image upscaling with streaming response
• Asynchronous Jobs: Submit multiple images for batch processing
• Multi-Model Support: Multiple Real-ESRGAN models (2x, 3x, 4x upscaling)
• Batch Processing: Process up to 100 images per batch request
• Model Management: Download and manage upscaling models
• Docker Deployment: Simplified containerized deployment
• Gitea CI/CD: Automatic Docker image building and publishing
• API Documentation: Interactive Swagger UI and ReDoc
• Health Checks: Kubernetes-ready liveness and readiness probes
• System Monitoring: CPU, memory, and disk metrics

Quick Start

Local Development

# 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 '{"models": ["RealESRGAN_x4plus"]}'

# Upscale an image (synchronous)
curl -X POST http://localhost:8000/api/v1/upscale \
  -F 'image=@input.jpg' \
  -F 'model=RealESRGAN_x4plus' \
  -o output.jpg

# Upscale asynchronously
curl -X POST http://localhost:8000/api/v1/jobs \
  -F 'image=@input.jpg' \
  -F 'model=RealESRGAN_x4plus'

# 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 output.jpg

API Endpoints

Upscaling

Method	Path	Description
POST	/api/v1/upscale	Synchronous upscaling (returns file directly)
POST	/api/v1/upscale-batch	Submit batch of images for async processing
POST	/api/v1/jobs	Create async upscaling job
GET	/api/v1/jobs	List all jobs
GET	/api/v1/jobs/{job_id}	Get job status
GET	/api/v1/jobs/{job_id}/result	Download job result

Model Management

Method	Path	Description
GET	/api/v1/models	List all available models
POST	/api/v1/models/download	Download models
GET	/api/v1/models/{model_name}	Get model information
POST	/api/v1/models/{model_name}/download	Download specific model
GET	/api/v1/models-info	Get models directory info

Health & System

Method	Path	Description
GET	/api/v1/health	Health check
GET	/api/v1/health/ready	Readiness probe
GET	/api/v1/health/live	Liveness probe
GET	/api/v1/system	System information
GET	/api/v1/stats	Request statistics
POST	/api/v1/cleanup	Clean up old jobs

Configuration

Configuration via environment variables (prefix: RSR_):

RSR_UPLOAD_DIR=/data/uploads           # Upload directory
RSR_OUTPUT_DIR=/data/outputs           # Output directory
RSR_MODELS_DIR=/data/models            # Models directory
RSR_TEMP_DIR=/data/temp                # Temporary directory
RSR_JOBS_DIR=/data/jobs                # Jobs directory
RSR_EXECUTION_PROVIDERS=["cpu"]        # Execution providers
RSR_EXECUTION_THREAD_COUNT=4           # Thread count
RSR_DEFAULT_MODEL=RealESRGAN_x4plus   # Default model
RSR_TILE_SIZE=400                      # Tile size for large images
RSR_TILE_PAD=10                        # Tile padding
RSR_MAX_UPLOAD_SIZE_MB=500             # Max upload size
RSR_SYNC_TIMEOUT_SECONDS=300           # Sync processing timeout
RSR_AUTO_CLEANUP_HOURS=24              # Auto cleanup interval

Available Models

{
    'RealESRGAN_x2plus': '2x upscaling',
    'RealESRGAN_x3plus': '3x upscaling',
    'RealESRGAN_x4plus': '4x upscaling (general purpose)',
    'RealESRGAN_x4plus_anime_6B': '4x upscaling (anime/art)',
}

Docker Deployment

Local/Development

docker compose build
docker compose up -d

Production

docker compose -f docker-compose.prod.yml up -d

Gitea CI/CD

The .gitea/workflows/build.yml automatically:

1. Builds Docker image
2. Publishes to Gitea Container Registry
3. Tags with git commit SHA and latest

Push to Gitea to trigger automatic builds:

git push gitea main

Architecture

app/
├── main.py              # FastAPI application
├── config.py            # Configuration settings
├── routers/             # API route handlers
│   ├── upscale.py      # Upscaling endpoints
│   ├── models.py       # Model management
│   └── health.py       # Health checks
├── services/            # Business logic
│   ├── realesrgan_bridge.py  # Real-ESRGAN integration
│   ├── file_manager.py       # File handling
│   ├── worker.py             # Async job queue
│   └── model_manager.py      # Model management
└── schemas/             # Pydantic models
    ├── upscale.py
    ├── models.py
    └── health.py

Performance

• Synchronous Upscaling: Best for small images (< 4MP)
• Asynchronous Jobs: Recommended for large batches or high concurrency
• Tile Processing: Efficiently handles images up to 8K resolution

Development

Install dependencies:

pip install -r requirements.txt

Run locally:

python -m uvicorn app.main:app --reload

License

This project follows the Real-ESRGAN license.

References

• Real-ESRGAN GitHub
• FastAPI Documentation
• Docker Documentation