realesrgan-api/README.md

# Real-ESRGAN API

REST API wrapping [Real-ESRGAN](https://github.com/xinntao/Real-ESRGAN) for image upscaling. Features synchronous and asynchronous (job-based) processing with multi-target Docker builds (CPU + CUDA GPU support).

## 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**: CPU and CUDA GPU support with multi-target builds
- **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, disk, and GPU metrics

## Quick Start

### Local Development (CPU)

```bash
# 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
```

### GPU Support

```bash
# Build with GPU support and run
docker compose -f docker-compose.gpu.yml build
docker compose -f docker-compose.gpu.yml up -d
```

## 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_`):

```bash
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

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

## Docker Deployment

### Development (CPU)

```bash
docker compose build
docker compose up -d
```

### Production (GPU)

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

## Gitea CI/CD

The `.gitea/workflows/build.yml` automatically:

1. Builds Docker images for CPU and GPU variants
2. Publishes to Gitea Container Registry
3. Tags with git commit SHA and latest

Push to Gitea to trigger automatic builds:

```bash
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
- **GPU Performance**: 2-5x faster than CPU depending on model and image size
- **Tile Processing**: Efficiently handles images up to 8K resolution

## Development

Install dependencies:

```bash
pip install -r requirements.txt -r requirements-cpu.txt
```

Run locally:

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

## License

This project follows the Real-ESRGAN license.

## References

- [Real-ESRGAN GitHub](https://github.com/xinntao/Real-ESRGAN)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [Docker Documentation](https://docs.docker.com/)