API_DOCS.md

Real-CUGAN API Docs

Base URL:

• Production: https://huanx-real-cugan-hf-api.hf.space
• Space page: https://huggingface.co/spaces/huanx/real-cugan-hf-api

Auth

Use one of:

• X-API-Key: <your_api_key>
• Authorization: Bearer <your_api_key>

API keys are created in the admin panel:

• https://huanx-real-cugan-hf-api.hf.space/admin

Endpoints

GET /

Returns service entrypoints.

Example response:

{
  "name": "Real-CUGAN Control Plane",
  "admin": "/admin",
  "health": "/healthz",
  "api": "/api/v1/upscale"
}

GET /healthz

Returns current health status.

Example response:

{
  "status": "ok",
  "busy": false,
  "models_loaded": [],
  "admin_configured": true
}

POST /api/v1/upscale

Upscales one image.

Request type:

• multipart/form-data

Form fields:

• file: required, input image
• scale: optional, 2 | 3 | 4
• variant: optional
• alpha: optional, 0.75 to 1.3
• tile_mode: optional, integer
• cache_mode: optional, 0 or 1
• response_format: optional, png | jpeg | webp

Current defaults:

• scale=2
• variant=no-denoise
• alpha=1.0
• tile_mode=3
• cache_mode=1
• response_format=png

Supported variants by scale:

• 2x: no-denoise, denoise1x, denoise2x, denoise3x, conservative
• 3x: no-denoise, denoise3x, conservative
• 4x: no-denoise, denoise3x, conservative

Input limits:

• minimum dimension: 8px
• max long edge: 1536px
• max pixels: 2400000

Response:

• binary image body
• content type matches response_format

Useful response headers:

• X-Job-Id
• X-Scale
• X-Variant
• X-Tile-Mode-Used
• X-Cache-Mode-Used
• X-Duration-Ms

Notes:

• Requests are serialized. Only one upscale runs at a time.
• png and webp preserve alpha when the source image has transparency.
• For very small images, the runtime may automatically downgrade tile settings to avoid upstream Real-CUGAN errors.

Quick Start

Set your variables first:

export BASE_URL="https://huanx-real-cugan-hf-api.hf.space"
export API_KEY="replace-with-your-api-key"

curl

curl -X POST "$BASE_URL/api/v1/upscale" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@input.png" \
  -F "scale=2" \
  -F "variant=no-denoise" \
  -F "alpha=1.0" \
  -F "response_format=png" \
  -o output.png

If you want response headers too:

curl -D response.headers.txt -X POST "$BASE_URL/api/v1/upscale" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@input.png" \
  -F "scale=2" \
  -F "variant=no-denoise" \
  -F "response_format=png" \
  -o output.png

Python

import requests

BASE_URL = "https://huanx-real-cugan-hf-api.hf.space"
API_KEY = "replace-with-your-api-key"

with open("input.png", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/api/v1/upscale",
        headers={"X-API-Key": API_KEY},
        files={"file": ("input.png", f, "image/png")},
        data={
            "scale": "2",
            "variant": "no-denoise",
            "alpha": "1.0",
            "response_format": "png",
        },
        timeout=180,
    )

response.raise_for_status()

with open("output.png", "wb") as f:
    f.write(response.content)

print("job_id:", response.headers.get("X-Job-Id"))
print("duration_ms:", response.headers.get("X-Duration-Ms"))

Node.js

Node 18+ example:

import fs from "node:fs";

const baseUrl = "https://huanx-real-cugan-hf-api.hf.space";
const apiKey = "replace-with-your-api-key";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("input.png")], { type: "image/png" }), "input.png");
form.append("scale", "2");
form.append("variant", "no-denoise");
form.append("alpha", "1.0");
form.append("response_format", "png");

const response = await fetch(`${baseUrl}/api/v1/upscale`, {
  method: "POST",
  headers: {
    "X-API-Key": apiKey,
  },
  body: form,
});

if (!response.ok) {
  throw new Error(await response.text());
}

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("output.png", buffer);

console.log("job_id:", response.headers.get("x-job-id"));
console.log("duration_ms:", response.headers.get("x-duration-ms"));

Example Variants

Typical quality choices:

• strongest general 2x anime upscale: scale=2, variant=no-denoise
• noisy or heavily compressed source: scale=2, variant=denoise1x or denoise2x
• aggressive cleanup: scale=2, variant=denoise3x
• safest / least destructive: scale=2, variant=conservative

For CPU Basic, recommended first try:

scale=2
variant=no-denoise
alpha=1.0
response_format=png

Error Codes

400 Bad Request

Common causes:

• missing file
• empty upload
• unsupported response_format
• image too small
• image exceeds configured size limits

Example:

{
  "detail": "Empty upload."
}

401 Unauthorized

Common causes:

• missing API key
• invalid API key
• disabled API key

Examples:

{
  "detail": "Missing API key."
}

{
  "detail": "Invalid API key."
}

429 Too Many Requests

The service only runs one upscale at a time.

Example:

{
  "detail": "Another inference is already running."
}

503 Service Unavailable

Common causes:

• runtime/model load failure
• missing weights
• unsupported model selection

Example:

{
  "detail": "Weight for 2x / no-denoise not found in /app/weights."
}

500 Internal Server Error

Unexpected inference failure.

Example:

{
  "detail": "Upscaling failed."
}

Admin

Admin panel:

• GET /admin/login
• GET /admin

Functions:

• create / disable / delete API keys
• adjust default runtime settings
• view job history and dashboard metrics
• change admin password

Minimal Integration Flow

1. Log in to /admin
2. Create an API key
3. Store it in your caller as X-API-Key
4. Send multipart/form-data to /api/v1/upscale
5. Save the binary response as an image file