upscaler

This skill does NOT:

• Generate new content — it ENHANCES existing pixels via super-resolution models
• Magic-restore an image from junk-tier (16×16 thumbnail to 4K HD) — input quality matters; garbage in, garbage out
• Handle video — one frame at a time only
• Vectorize — output remains raster PNG
• Remove background (chain with bg-remover)
• Fix major artifacts (deep blur, motion blur, JPEG mosquito noise at extreme levels) — works best on mildly low-res / soft images

ROLE

Read input image → call a Replicate-hosted upscaler → save the upscaled output at the requested scale factor.

PIPELINE

1. Resolve input:

   • --image <path-or-url> (required)

2. Pick provider:

   • Default: nightmareai/real-esrgan (popular general-purpose, ~$0.005/image at 4×)
   • Alternatives via --replicate-model <id>:
     • nightmareai/real-esrgan — default; best general
     • tencentarc/gfpgan — face-focused (best for portraits)
     • jingyunliang/swinir — alternative general
     • philz1337x/clarity-upscaler — high-fidelity preservation, slower
   • Other Replicate upscalers: pass via --replicate-model <slug>

3. Scale: --scale 2|4|8 (default 4).

4. Face enhance (optional): --face-enhance enables face restoration (Real-ESRGAN supports GFPGAN-style face restoration as a flag).

5. Execute via the Replicate router (REPLICATE_API_TOKEN required).

6. Save:

   • Default: ./generated/upscaled/<input-stem>-4x.png (or -2x.png / -8x.png)
   • Custom: --output <path>

MODES

Required

• upscaler --image <path-or-url>

Options

• --scale 2|4|8 — upscaling factor (default 4)
• --output <path> — explicit output path
• --replicate-model <id> — override default upscaler model
• --face-enhance — enable face restoration (works with Real-ESRGAN, GFPGAN)
• --yes — skip cost confirmation
• --check — verify REPLICATE_API_TOKEN + connectivity

REFERENCES (load on demand)

File	When to load
references/providers.md	Replicate upscaler model comparison + when to pick which
references/use-cases.md	Real-world scenarios (old photo restoration, product shots, low-res AI gen output)
references/troubleshoot.md	When output is blurry, faces get distorted, artifacts appear

EXAMPLES

See examples/before-after.md — 3 calibration runs: AI-gen image at higher resolution, old family photo restoration, product shot enhancement.

CONSTRAINTS

• Single image per call. For batch: run in a shell loop.

• Replicate API key required. Set via /skills-keys add REPLICATE_API_TOKEN r8_....

• Cost: ~$0.005-0.02 per image depending on model and scale. 4× cheapest; 8× ~3× more expensive.

• Input quality matters. Models can enhance mildly-low-res images (480p → 1920p, soft → sharp). They CANNOT magic-restore severely degraded images.

• Face preservation: use --face-enhance or switch to --replicate-model tencentarc/gfpgan for portraits. Without this, generic upscalers may distort facial features.

• Output dimensions = input × scale factor. A 512×512 input at --scale 4 → 2048×2048 output. Plan disk space.

• Output format is PNG by default. Source format preserved when possible; transparent backgrounds maintained.

• Default 4× is the most-supported scale across all upscalers. Some models don't support 8×.

• No re-encoding to JPEG by skill. If you need JPEG: convert after via magick or Photoshop / Affinity.

• Never print API keys.

• Output dir is ./generated/upscaled/ by default.

INVOCATION HINTS

When the user says any of:

• "upscale this image", "enhance the resolution"
• "make this bigger / sharper", "fix this low-res image"
• "4x upscale", "8x upscale"
• "улучши разрешение", "увеличь фотку", "апскейл", "повысь разрешение"
• "сделай четче"

Defaults: --image <path> (required); 4× via Real-ESRGAN; saves to ./generated/upscaled/<stem>-4x.png.

For portrait / face photos: prefer --face-enhance or --replicate-model tencentarc/gfpgan.

For AI-gen output to upscale: default (Real-ESRGAN) works well; the model is trained on a mix of real + AI imagery.

This skill is distinct from:

• image-prompt / cover-maker / etc. — they GENERATE new images. This ENHANCES existing.
• bg-remover — that's segmentation (transparent BG). This is super-resolution.
• style-transfer (planned) — that's stylization. This is resolution.
• style-check etc. — those are text linters, not visual utilities.