Hugging Face's logo

Spaces:
huanx
/
real-cugan-hf-api
Sleeping

App Files Community
real-cugan-hf-api / README.md
huanx's picture
huanx
Restore first public web UI commit 8ee6d52
e203363 verified
preview code
|
Raw
History Blame Contribute Delete
2.85 kB
metadata 
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 

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.