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:

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

### `GET /healthz`

Returns current health status.

Example response:

```json
{
  "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:

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

### curl

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

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

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

```js
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:

```text
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:

```json
{
  "detail": "Empty upload."
}
```

### `401 Unauthorized`

Common causes:

- missing API key
- invalid API key
- disabled API key

Examples:

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

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

### `429 Too Many Requests`

The service only runs one upscale at a time.

Example:

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

### `503 Service Unavailable`

Common causes:

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

Example:

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

### `500 Internal Server Error`

Unexpected inference failure.

Example:

```json
{
  "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