Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumenfall.ai/llms.txt

Use this file to discover all available pages before exploring further.

Upscaling increases the resolution of an existing image. Lumenfall routes upscaling to specialized models (Topaz, Recraft, Clarity, Real-ESRGAN, and others) that produce sharper results than naive resizing and preserve detail better than general-purpose edit models.
Same endpoint, different mode. Upscaling uses the image edit endpoint - just pass model, image, and scale_factor. No prompt is required. Lumenfall detects upscale mode from the presence of scale_factor and routes the request accordingly.

​
Quick start

curl https://api.lumenfall.ai/openai/v1/images/edits \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "model=topaz-image-upscale" \
  -F "image=@capybara.png" \
  -F "scale_factor=4"
Response
{
  "created": 1702345678,
  "size": "4096x4096",
  "data": [
    {
      "url": "https://media.lumenfall.ai/abc123.png"
    }
  ],
  "metadata": {
    "model": "topaz-image-upscale",
    "executed_model": "fal/fal-ai/topaz/upscale/image",
    "provider": "fal",
    "provider_name": "fal.ai",
    "cost": 0.05,
    "cost_currency": "USD"
  }
}

​
Available models

The full set is in the model catalog. Headline models:
Model IDBest forNotes
topaz-image-upscalePhoto-realistic upscaling, broad input rangeSupports fractional scale_factor
recraft-crisp-upscaleSharp, photographic detail recoveryFixed scale, no scale_factor needed
recraft-creative-upscaleStylized / illustrated contentFixed scale, no scale_factor needed
clarity-upscalerDetail enhancement with creative latitude—
crystal-upscalerFast general-purpose upscalingPer-megapixel pricing
real-esrganAnime, line art, low-res photosDefault scale 4
seedvr-image-upscaleHigh-fidelity photo upscalingPer-megapixel pricing
aura-srSuper-resolution for small inputsDefault scale 4
google-upscalerVertex-backed photo upscalingScale 2 or 4 only

​
Parameters

The endpoint accepts everything documented for Edit images, plus:
​
scale_factor
number
How much to scale the image. The output is scale_factor times the input dimensions on each axis (e.g., 2 doubles width and height, 4 quadruples them). Supported values vary by model - Topaz and SeedVR accept fractional values, Google upscaler accepts only 2 or 4, and Recraft upscalers ignore this parameter (their scale is fixed). When omitted, each model uses its default (typically 2, except 4 for ESRGAN-family models).
prompt is not required for upscaling. If you pass one, most upscale models will ignore it. A few models (such as Topaz Redefine variants) accept an optional guidance prompt - check the model catalog for per-model details.

​
Common patterns

​
Generate, then upscale

A common workflow is to generate at a fast, cheap resolution and upscale only the keepers: 
from openai import OpenAI

client = OpenAI(
    api_key="lmnfl_your_api_key",
    base_url="https://api.lumenfall.ai/openai/v1",
)

# 1. Generate at 1024x1024
draft = client.images.generate(
    model="flux.2-max",
    prompt="A capybara enjoying a hot spring at sunset, photorealistic",
    size="1024x1024",
)
draft_url = draft.data[0].url

# 2. Upscale 4x to 4096x4096
final = client.images.edit(
    model="topaz-image-upscale",
    image=draft_url,
    extra_body={"scale_factor": 4},
)

print(final.data[0].url)
You can pass either a file or a URL as image. URLs are convenient for chaining since you can hand the previous response straight back into the next call.

​
Edit, then upscale

The same pattern works after an edit: 
edited = client.images.edit(
    model="gemini-3-pro-image",
    image=open("capybara.png", "rb"),
    prompt="Add a tiny straw hat",
)

upscaled = client.images.edit(
    model="topaz-image-upscale",
    image=edited.data[0].url,
    extra_body={"scale_factor": 2},
)

​
Cost estimation

Upscaling costs vary substantially by model and input size - per-megapixel models scale with output dimensions, while per-image models charge a flat rate per call. Use dry run mode to estimate before running: 
curl "https://api.lumenfall.ai/openai/v1/images/edits?dryRun=true" \
  -H "Authorization: Bearer $LUMENFALL_API_KEY" \
  -F "model=topaz-image-upscale" \
  -F "image=@capybara.png" \
  -F "scale_factor=4"

​
Best practices

Photographs upscale best with topaz-image-upscale or seedvr-image-upscale. Anime, pixel art, and line work do better with real-esrgan. Stylized illustrations benefit from recraft-creative-upscale.
A 4x upscale of a 4096x4096 image produces a 16384x16384 result - large, slow, and expensive. Most use cases are well-served by 2x. Reach for 4x when the input is small or the output target is print-quality.
JPEG compression artifacts get amplified during upscaling. If you control the source, use PNG or WebP. If you don’t, accept that JPEG inputs will produce JPEG-quality outputs.
Per-megapixel pricing means a 2048x2048 input costs 4x what a 1024x1024 input costs - even at the same scale_factor. Always dry-run with the real image dimensions before batching.

​
Next steps

Edit images

Full reference for the underlying endpoint, including all shared parameters and the response shape.

Cost estimation

Use ?dryRun=true to estimate before running.