> ## 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.

# Image upscaling

> Increase image resolution with dedicated upscaling models

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.

<Info>
  **Same endpoint, different mode.** Upscaling uses the [image edit endpoint](/api-reference/images/edit) - 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.
</Info>

## Quick start

<CodeGroup>
  ```bash HTTP theme={null}
  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"
  ```

  ```python Python theme={null}
  from openai import OpenAI

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

  response = client.images.edit(
      model="topaz-image-upscale",
      image=open("capybara.png", "rb"),
      extra_body={"scale_factor": 4},
  )

  print(response.data[0].url)
  ```

  ```typescript JavaScript / TypeScript theme={null}
  import OpenAI from "openai";
  import fs from "fs";

  const client = new OpenAI({
    apiKey: "lmnfl_your_api_key",
    baseURL: "https://api.lumenfall.ai/openai/v1",
  });

  const response = await client.images.edit({
    model: "topaz-image-upscale",
    image: fs.createReadStream("capybara.png"),
    // @ts-expect-error - scale_factor is a Lumenfall extension
    scale_factor: 4,
  });

  console.log(response.data[0].url);
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      "os"

      "github.com/openai/openai-go"
      "github.com/openai/openai-go/option"
  )

  func main() {
      client := openai.NewClient(
          option.WithAPIKey("lmnfl_your_api_key"),
          option.WithBaseURL("https://api.lumenfall.ai/openai/v1"),
          option.WithJSONSet("scale_factor", 4),
      )

      file, _ := os.Open("capybara.png")
      defer file.Close()

      response, err := client.Images.Edit(context.Background(), openai.ImageEditParams{
          Model: openai.F("topaz-image-upscale"),
          Image: openai.F[openai.ImageEditParamsImageUnion](file),
      })
      if err != nil {
          panic(err)
      }

      fmt.Println(response.Data[0].URL)
  }
  ```

  ```ruby Ruby theme={null}
  require "openai"

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

  response = client.images.edit(
    model: "topaz-image-upscale",
    image: File.open("capybara.png", "rb"),
    scale_factor: 4
  )

  puts response.data[0].url
  ```
</CodeGroup>

```json Response theme={null}
{
  "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](https://lumenfall.ai/models?capability=upscaling). Headline models:

| Model ID                   | Best for                                     | Notes                                 |
| -------------------------- | -------------------------------------------- | ------------------------------------- |
| `topaz-image-upscale`      | Photo-realistic upscaling, broad input range | Supports fractional `scale_factor`    |
| `recraft-crisp-upscale`    | Sharp, photographic detail recovery          | Fixed scale, no `scale_factor` needed |
| `recraft-creative-upscale` | Stylized / illustrated content               | Fixed scale, no `scale_factor` needed |
| `clarity-upscaler`         | Detail enhancement with creative latitude    | —                                     |
| `crystal-upscaler`         | Fast general-purpose upscaling               | Per-megapixel pricing                 |
| `real-esrgan`              | Anime, line art, low-res photos              | Default scale `4`                     |
| `seedvr-image-upscale`     | High-fidelity photo upscaling                | Per-megapixel pricing                 |
| `aura-sr`                  | Super-resolution for small inputs            | Default scale `4`                     |
| `google-upscaler`          | Vertex-backed photo upscaling                | Scale `2` or `4` only                 |

## Parameters

The endpoint accepts everything documented for [Edit images](/api-reference/images/edit), plus:

<ParamField body="scale_factor" type="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).
</ParamField>

<Note>
  `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](https://lumenfall.ai/models?capability=upscaling) for per-model details.
</Note>

## Common patterns

### Generate, then upscale

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

```python theme={null}
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:

```python theme={null}
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](/api-reference/cost-estimation) to estimate before running:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Match the model to the input">
    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`.
  </Accordion>

  <Accordion title="Don't over-scale">
    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.
  </Accordion>

  <Accordion title="Start from PNG when possible">
    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.
  </Accordion>

  <Accordion title="Run cost estimation on the actual input">
    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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Edit images" icon="wand-magic-sparkles" href="/api-reference/images/edit">
    Full reference for the underlying endpoint, including all shared parameters and the response shape.
  </Card>

  <Card title="Cost estimation" icon="calculator" href="/api-reference/cost-estimation">
    Use `?dryRun=true` to estimate before running.
  </Card>
</CardGroup>