---
title: Real-CUGAN Control Plane
emoji: 🖼️
colorFrom: yellow
colorTo: green
sdk: docker
app_port: 7860
---

# Real-CUGAN Control Plane

CPU-first Hugging Face Space for anime image upscaling with:

- Beginner-friendly browser web UI at `/`
- API key protected `/api/v1/upscale`
- Admin login, key management, runtime controls
- Job history and lightweight dashboard
- Real-CUGAN lazy loading on CPU

## Required setup

1. Put one or more Real-CUGAN weight files into `weights/`.
2. Set `ADMIN_PASSWORD` as a Hugging Face Space secret.
3. Optional: set `SESSION_SECRET`, `BOOTSTRAP_API_KEY`, `REAL_CUGAN_WEIGHT_BASE_URL`.

Recommended Hugging Face Space secrets:

- `ADMIN_PASSWORD`: required unless you want to initialize the admin account in the browser
- `SESSION_SECRET`: recommended for stable admin sessions across restarts
- `BOOTSTRAP_API_KEY`: optional first API key created at boot
- `BOOTSTRAP_API_KEY_NAME`: optional label for the bootstrap key
- `REAL_CUGAN_WEIGHT_BASE_URL`: optional base URL if you host weights remotely
- `SESSION_HTTPS_ONLY=true`: recommended once the Space is running behind HTTPS

Recommended 2x weights:

- `up2x-latest-no-denoise.pth`
- `up2x-latest-denoise1x.pth`
- `up2x-latest-denoise2x.pth`
- `up2x-latest-denoise3x.pth`
- `up2x-latest-conservative.pth`

Optional 3x / 4x weights:

- `up3x-latest-no-denoise.pth`
- `up3x-latest-denoise3x.pth`
- `up3x-latest-conservative.pth`
- `up4x-latest-no-denoise.pth`
- `up4x-latest-denoise3x.pth`
- `up4x-latest-conservative.pth`

## API

Use either `X-API-Key: <key>` or `Authorization: Bearer <key>`.

Full API docs:

- `API_DOCS.md`

`POST /api/v1/upscale`

Multipart form fields:

- `file`: source image
- `scale`: `2`, `3`, `4`
- `variant`: `no-denoise`, `denoise1x`, `denoise2x`, `denoise3x`, `conservative`
- `alpha`: `0.75` to `1.3`
- `tile_mode`: optional override
- `cache_mode`: optional override
- `response_format`: `png`, `jpeg`, `webp`

The admin panel is at `/admin`.

## Local run

```bash
cd /home/huanx/code/real-cugan-hf-api
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install torch==2.5.1 --index-url https://download.pytorch.org/whl/cpu
pip install -r requirements.txt
export ADMIN_PASSWORD='change-me-now'
uvicorn app.main:app --host 0.0.0.0 --port 7860
```

Open `http://127.0.0.1:7860/` for the public web upscaler.
Open `http://127.0.0.1:7860/admin` for the admin console.

## Notes

- The app stores only metadata in SQLite. Uploaded images are processed in memory and are not persisted by default.
- The runtime loads `upcunet_v3.py` from the pinned Real-CUGAN upstream commit on first use and verifies its checksum.
- API requests are serialized. One active upscale runs at a time by design.
- Without CPU PyTorch or missing weights, the API responds with a clear `503` describing the runtime issue.