fal Assets is now live!
Docs
Log-inSign-up

fal-ai/topaz/upscale/image

Use the powerful and accurate topaz image enhancer to enhance your images.
Inference
Commercial use
Partner
Schema
LLMs
PlaygroundAPI
Open in Sandbox

Table of contents

About

Upscale Image

1. Calling the API#

Install the client#

The client provides a convenient way to interact with the model API.

npm install --save @fal-ai/client

Setup your API Key#

Set FAL_KEY as an environment variable in your runtime.

export FAL_KEY="YOUR_API_KEY"

Submit a request#

The client API handles the API submit protocol. It will handle the request status updates and return the result when the request is completed.

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/topaz/upscale/image", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg"
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);

2. Authentication#

The API uses an API Key for authentication. It is recommended you set the FAL_KEY environment variable in your runtime when possible.

API Key#

In case your app is running in an environment where you cannot set environment variables, you can set the API Key manually as a client configuration.
import { fal } from "@fal-ai/client";

fal.config({
  credentials: "YOUR_FAL_KEY"
});

3. Queue#

Submit a request#

The client API provides a convenient way to submit requests to the model.

import { fal } from "@fal-ai/client";

const { request_id } = await fal.queue.submit("fal-ai/topaz/upscale/image", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg"
  },
  webhookUrl: "https://optional.webhook.url/for/results",
});

Fetch request status#

You can fetch the status of a request to check if it is completed or still in progress.

import { fal } from "@fal-ai/client";

const status = await fal.queue.status("fal-ai/topaz/upscale/image", {
  requestId: "764cabcf-b745-4b3e-ae38-1200304cf45b",
  logs: true,
});

Get the result#

Once the request is completed, you can fetch the result. See the Output Schema for the expected result format.

import { fal } from "@fal-ai/client";

const result = await fal.queue.result("fal-ai/topaz/upscale/image", {
  requestId: "764cabcf-b745-4b3e-ae38-1200304cf45b"
});
console.log(result.data);
console.log(result.requestId);

4. Files#

Some attributes in the API accept file URLs as input. Whenever that's the case you can pass your own URL or a Base64 data URI.

Data URI (base64)#

You can pass a Base64 data URI as a file input. The API will handle the file decoding for you. Keep in mind that for large files, this alternative although convenient can impact the request performance.

Hosted files (URL)#

You can also pass your own URLs as long as they are publicly accessible. Be aware that some hosts might block cross-site requests, rate-limit, or consider the request as a bot.

Uploading files#

We provide a convenient file storage that allows you to upload files and use them in your requests. You can upload files using the client API and use the returned URL in your requests.

import { fal } from "@fal-ai/client";

const file = new File(["Hello, World!"], "hello.txt", { type: "text/plain" });
const url = await fal.storage.upload(file);

Read more about file handling in our file upload guide.

5. Schema#

Input#

image_url string* required

Url of the image to be upscaled

model ModelEnum

Model to use for image enhancement, grouped by family. Precision — Standard V2 fits most photos, High Fidelity V2 preserves detail in professional shots, Low Resolution V2 recovers compressed sources, CGI targets art and rendered graphics, Text Refine keeps text and shapes crisp. Generative — Wonder 3.5 is the latest Wonder with finer detail, Wonder 3 is Topaz's most advanced generative realism model, Redefine adds prompt-guided creative detail, Standard MAX maximizes quality, Recovery/Recovery V2 rebuild extreme low-resolution images. Creative — Bloom 2 creatively upscales AI-generated images. The newly added models bill at a higher rate than the base price (Wonder 3.5 2x, Bloom 2 8x). Default value: "Standard V2"

Possible enum values: Standard V2, High Fidelity V2, Low Resolution V2, CGI, Text Refine, Wonder 3.5, Wonder 3, Wonder, Standard MAX, Redefine, Recovery V2, Recovery, Bloom 2

upscale_factor float

Factor to upscale the image by (e.g. 2.0 doubles width and height) Default value: 2

crop_to_fill boolean
output_format OutputFormatEnum

Output format of the upscaled image. Default value: "jpeg"

Possible enum values: jpeg, png

subject_detection SubjectDetectionEnum

Subject detection mode for the image enhancement. Applies to standard enhance and Recovery V2 models. Default value: "All"

Possible enum values: All, Foreground, Background

face_enhancement boolean

Whether to apply face enhancement to the image. Applies to standard enhance and Recovery V2 models. Default value: true

face_enhancement_creativity float

Creativity level for face enhancement. 0.0 means no creativity, 1.0 means maximum creativity. Ignored if face enhancement is disabled.

face_enhancement_strength float

Strength of the face enhancement. 0.0 means no enhancement, 1.0 means maximum enhancement. Ignored if face enhancement is disabled. Default value: 0.8

sharpen float

Sharpening level (0.0-1.0). Applies to Standard V2, Low Resolution V2, CGI, High Fidelity V2, Text Refine, and Redefine models.

denoise float

Denoising level (0.0-1.0). Applies to Standard V2, Low Resolution V2, CGI, High Fidelity V2, Text Refine, and Redefine models.

fix_compression float

Compression artifact removal level (0.0-1.0). Applies to Standard V2, Low Resolution V2, High Fidelity V2, and Text Refine models.

strength float

Enhancement strength (0.01-1.0). Applies to Text Refine model only.

creativity integer

Creativity level for generative upscaling. Higher values produce more creative/hallucinated details. Redefine supports 1-6; Bloom 2 supports 1-9.

texture integer

Texture detail level for generative upscaling (1-5). Applies to Redefine model only.

prompt string

Text prompt to guide generative upscaling (max 1024 chars). Applies to Redefine model only.

autoprompt boolean

Enable automatic prompt generation for generative upscaling. Applies to Redefine and Bloom 2 models.

color_preservation boolean

Preserve the source image's colors in the output. Applies to Bloom 2 model only.

detail float

Detail recovery level (0.0-1.0). Applies to Recovery V2 model only.

enhancement_strength Enum

Enhancement strength for generative upscaling. Applies to Wonder 3 and Wonder 3.5 models. When omitted, Topaz auto-configures it.

Possible enum values: low, medium, high

{
  "image_url": "https://storage.googleapis.com/falserverless/model_tests/codeformer/codeformer_poor_1.jpeg",
  "model": "Standard V2",
  "upscale_factor": 2,
  "output_format": "jpeg",
  "subject_detection": "All",
  "face_enhancement": true,
  "face_enhancement_strength": 0.8
}

Output#

image File* required

The upscaled image.

{
  "image": {
    "url": "",
    "content_type": "image/png",
    "file_name": "z9RV14K95DvU.png",
    "file_size": 4404019
  }
}

Other types#

VideoSdrToHdrRequest#

video_url string* required

URL of the SDR video to convert to HDR

ImageDenoiseGenerativeRequest#

image_url string* required

Url of the image to process

output_format OutputFormatEnum

Output format of the processed image. Default value: "jpeg"

Possible enum values: jpeg, png

model string

Highest-quality generative denoising with intelligent detail recovery. Default value: "Denoise Max"

StrongAIUpscaleRequest#

video_url string* required

URL of the AI-generated video to upscale

target_width integer

Target width of the output video Default value: 5120

target_height integer

Target height of the output video Default value: 2880

target_fps integer

Target FPS for the output video. Defaults to source FPS if not specified.

VideoDeblurRequest#

video_url string* required

URL of the video to deblur (motion deblur, Themis 2)

H264_output boolean

Whether to use H264 codec for output video. Default is H265.

ImageTransparentUpscaleRequest#

image_url string* required

Url of the image to process

output_format string

Transparent upscaling always outputs PNG to preserve the alpha channel. Default value: "png"

upscale_factor float

Factor to upscale the image by (e.g. 2.0 doubles width and height). Default value: 2

RecoverUpscaleRequest#

video_url string* required

URL of the low-quality video to upscale and recover

upscale_factor float

Factor to upscale the video by (e.g. 2.0 doubles width and height) Default value: 2

target_fps integer

Target FPS for the output video. Defaults to source FPS if not specified.

ImageAdjustRequest#

image_url string* required

Url of the image to process

output_format OutputFormatEnum

Output format of the processed image. Default value: "jpeg"

Possible enum values: jpeg, png

model ModelEnum

Color & lighting correction. Adjust V2 fixes exposure/lighting; White Balance corrects color; Colorize adds color to B&W images. Default value: "Adjust V2"

Possible enum values: Adjust V2, White Balance, Colorize

VideoDenoiseRequest#

video_url string* required

URL of the video to denoise

model ModelEnum

Denoise model. Nyx is high-quality denoising with texture preservation; Nyx Fast trades quality for speed on high-volume workloads; Nyx XL targets extreme noise; Nyx HF is precision denoising for pipeline-ready outputs (denoise only, no upscaling). Default value: "Nyx"

Possible enum values: Nyx, Nyx Fast, Nyx XL, Nyx HF

upscale_factor float

Optional upscale applied on top of denoising. 1.0 keeps the source resolution. Default value: 1

noise float

Noise reduction level (0.0-1.0). Default varies by model.

compression float

Compression artifact removal level (0.0-1.0). Default varies by model.

halo float

Halo reduction level (0.0-1.0). Default varies by model.

H264_output boolean

Whether to use H264 codec for output video. Default is H265.

ImageDenoiseRequest#

image_url string* required

Url of the image to process

output_format OutputFormatEnum

Output format of the processed image. Default value: "jpeg"

Possible enum values: jpeg, png

model ModelEnum

Denoise model. Normal is general-purpose; Strong and Extreme remove progressively more noise. Default value: "Normal"

Possible enum values: Normal, Strong, Extreme

VideoFrameInterpolationRequest#

video_url string* required

URL of the video to retime / interpolate

model ModelEnum

Frame interpolation model. Apollo is general-purpose; Chronos targets real-world motion; Aion handles extreme/complex motion. Default value: "Apollo"

Possible enum values: Apollo, Chronos, Aion

target_fps integer

Target frames per second for the interpolated output. Default value: 60

H264_output boolean

Whether to use H264 codec for output video. Default is H265.

ImageSharpenRequest#

image_url string* required

Url of the image to process

output_format OutputFormatEnum

Output format of the processed image. Default value: "jpeg"

Possible enum values: jpeg, png

model ModelEnum

Sharpen model tuned per blur type (defocus, motion, portrait, wildlife, …). Default value: "Standard"

Possible enum values: Standard, Strong, Lens Blur V2, Motion Blur, Natural, Refocus, Wildlife, Portrait, Auto Sharpen

VideoUpscaleRequest#

video_url string* required

URL of the video to upscale

model ModelEnum

Video enhancement model, grouped by family. Precision — Proteus fits most footage, Artemis denoises and sharpens degraded sources, Gaia HQ/CG refine rendered content, Gaia 2 handles animation and motion graphics at 2x. Denoise — Nyx models are dedicated noise reduction. Generative — Starlight models use diffusion for restoration and upscaling. Starlight Precise 1, Starlight Precise 2 and Starlight Fast 1 are deprecated by Topaz; prefer Starlight Precise 2.5 or Starlight Fast 2. Default value: "Proteus"

Possible enum values: Proteus, Artemis HQ, Artemis MQ, Artemis LQ, Gaia HQ, Gaia CG, Gaia 2, Nyx, Nyx Fast, Nyx XL, Nyx HF, Starlight Precise 2.5, Starlight HQ, Starlight Mini, Starlight Sharp, Starlight Fast 2, Starlight Precise 1, Starlight Precise 2, Starlight Fast 1

upscale_factor float

Factor to upscale the video by (e.g. 2.0 doubles width and height) Default value: 2

target_fps integer

Target FPS for frame interpolation. If set, frame interpolation will be enabled.

compression float

Compression artifact removal level (0.0-1.0). Default varies by model.

noise float

Noise reduction level (0.0-1.0). Default varies by model.

halo float

Halo reduction level (0.0-1.0). Default varies by model.

grain float

Film grain amount (0.0-0.1). Default varies by model.

recover_detail float

Recover original detail level (0.0-1.0). Higher values preserve more original detail.

H264_output boolean

Whether to use H264 codec for output video. Default is H265.

ImagePrecisionUpscaleRequest#

image_url string* required

Url of the image to be upscaled

model ModelEnum

Precision upscaling model. Standard V2 fits most photos; High Fidelity V3/V2 preserve detail in professional shots; Low Resolution V2 recovers compressed sources; CGI targets art and rendered graphics; Text Refine keeps text and shapes crisp. Default value: "Standard V2"

Possible enum values: Standard V2, High Fidelity V3, High Fidelity V2, Low Resolution V2, CGI, Text Refine

upscale_factor float

Factor to upscale the image by (e.g. 2.0 doubles width and height) Default value: 2

crop_to_fill boolean
output_format OutputFormatEnum

Output format of the upscaled image. Default value: "jpeg"

Possible enum values: jpeg, png

subject_detection SubjectDetectionEnum

Subject detection mode for the image enhancement. Default value: "All"

Possible enum values: All, Foreground, Background

face_enhancement boolean

Whether to apply face enhancement to the image. Default value: true

face_enhancement_creativity float

Creativity level for face enhancement. 0.0 means no creativity, 1.0 means maximum creativity. Ignored if face enhancement is disabled.

face_enhancement_strength float

Strength of the face enhancement. 0.0 means no enhancement, 1.0 means maximum enhancement. Ignored if face enhancement is disabled. Default value: 0.8

sharpen float

Sharpening level (0.0-1.0). Default varies by model.

denoise float

Denoising level (0.0-1.0). Default varies by model.

fix_compression float

Compression artifact removal level (0.0-1.0). Not supported by the CGI model.

strength float

Enhancement strength (0.01-1.0). Applies to Text Refine model only.

ImageRestoreRequest#

image_url string* required

Url of the image to process

output_format OutputFormatEnum

Output format of the processed image. Default value: "jpeg"

Possible enum values: jpeg, png

model ModelEnum

Restoration. Recover 3 rebuilds natural detail; Dust-Scratch V2 cleans up film dust and scratches. Default value: "Recover 3"

Possible enum values: Recover 3, Dust-Scratch V2

File#

url string* required

The URL where the file can be downloaded from.

content_type string

The mime type of the file.

file_name string

The name of the file. It will be auto-generated if not provided.

file_size integer

The size of the file in bytes.

VideoColorizeRequest#

video_url string* required

URL of the black-and-white video to colorize

H264_output boolean

Whether to use H264 codec for output video. Default is H265.

VideoGenerativeUpscaleRequest#

video_url string* required

URL of the video to upscale

model ModelEnum

Generative diffusion enhancement model. Starlight Precise 2.5 adds realism to AI-generated video; Starlight HQ maximizes quality on high-resolution sources; Starlight Mini restores archival footage; Starlight Sharp is fast restoration with sharper detail; Starlight Fast 2 is the fastest, cheapest diffusion upscaler. Default value: "Starlight Precise 2.5"

Possible enum values: Starlight Precise 2.5, Starlight HQ, Starlight Mini, Starlight Sharp, Starlight Fast 2

upscale_factor float

Factor to upscale the video by (e.g. 2.0 doubles width and height) Default value: 2

target_fps integer

Target FPS for frame interpolation. If set, frame interpolation will be enabled.

H264_output boolean

Whether to use H264 codec for output video. Default is H265.

VideoPrecisionUpscaleRequest#

video_url string* required

URL of the video to upscale

model ModelEnum

Precision (non-generative) enhancement model. Proteus fits most real-world footage; Proteus Natural is a softer variant; Iris recovers faces; Dione deinterlaces legacy/interlaced sources; Artemis denoises and sharpens degraded footage; Gaia refines high-quality footage and CG (Gaia 2 upscales animation at 2x); Rhea maximizes fine detail via an internal 4x pass; Theia gives manual detail/fidelity control. Default value: "Proteus"

Possible enum values: Proteus, Proteus Natural, Iris, Iris Low Quality, Dione DV, Dione TV, Dione Robust, Dione Dehalo, Dione Robust Dehalo, Artemis High Quality, Artemis Medium Quality, Artemis Low Quality, Artemis Strong Halo, Artemis Medium Halo, Artemis Aliasing & Moire, Gaia HQ, Gaia CG, Gaia 2, Rhea, Theia Fine Tune Detail, Theia Fine Tune Fidelity

upscale_factor float

Factor to upscale the video by (e.g. 2.0 doubles width and height) Default value: 2

target_fps integer

Target FPS for frame interpolation. If set, frame interpolation will be enabled.

compression float

Compression artifact removal level (0.0-1.0). Default varies by model.

noise float

Noise reduction level (0.0-1.0). Default varies by model.

halo float

Halo reduction level (0.0-1.0). Default varies by model.

grain float

Film grain amount (0.0-0.1). Default varies by model.

recover_detail float

Recover original detail level (0.0-1.0). Higher values preserve more original detail.

H264_output boolean

Whether to use H264 codec for output video. Default is H265.

ImageSharpenGenerativeRequest#

image_url string* required

Url of the image to process

output_format OutputFormatEnum

Output format of the processed image. Default value: "jpeg"

Possible enum values: jpeg, png

model ModelEnum

Generative deblur for severely blurred images. Super Focus V3 is the latest. Default value: "Super Focus V3"

Possible enum values: Super Focus V3, Super Focus V2

SlowMotionRequest#

video_url string* required

URL of the video to apply slow motion to

slowdown_factor integer

Factor to slow down the video by (e.g. 4 means 4x slower) Default value: 4

upscale_factor float

Optional factor to upscale the video by (e.g. 2.0 doubles width and height)

ImageGenerativeUpscaleRequest#

image_url string* required

Url of the image to be upscaled

model ModelEnum

Generative upscaling model. Wonder 3.5 is the latest Wonder with finer detail and fewer repetitive patterns; Wonder 3 is Topaz's most advanced generative realism model (Wonder 2/Wonder are earlier generations); Recover 3 rebuilds natural detail; Standard MAX is high-quality precision-leaning upscaling; Redefine adds prompt-guided creative detail; Recovery and Recovery V2 rebuild extreme low-resolution images. Default value: "Wonder 3"

Possible enum values: Wonder 3.5, Wonder 3, Wonder 2, Wonder, Recover 3, Standard MAX, Redefine, Recovery V2, Recovery

upscale_factor float

Factor to upscale the image by (e.g. 2.0 doubles width and height) Default value: 2

crop_to_fill boolean
output_format OutputFormatEnum

Output format of the upscaled image. Default value: "jpeg"

Possible enum values: jpeg, png

subject_detection SubjectDetectionEnum

Subject detection mode for the image enhancement. Applies to Wonder 3, Recovery and Recovery V2 models. Default value: "All"

Possible enum values: All, Foreground, Background

face_enhancement boolean

Whether to apply face enhancement to the image. Default value: true

face_enhancement_creativity float

Creativity level for face enhancement. 0.0 means no creativity, 1.0 means maximum creativity. Ignored if face enhancement is disabled.

face_enhancement_strength float

Strength of the face enhancement. 0.0 means no enhancement, 1.0 means maximum enhancement. Ignored if face enhancement is disabled. Default value: 0.8

enhancement_strength Enum

Enhancement strength for generative upscaling. Applies to Wonder 3 and Wonder 3.5 models. When omitted, Topaz auto-configures it.

Possible enum values: low, medium, high

creativity integer

Creativity level for generative upscaling (1-6). Higher values produce more creative/hallucinated details. Applies to Redefine model only.

texture integer

Texture detail level for generative upscaling (1-5). Applies to Redefine model only.

prompt string

Text prompt to guide generative upscaling (max 1024 chars). Applies to Redefine model only.

autoprompt boolean

Enable automatic prompt generation for generative upscaling. Applies to Redefine model only.

sharpen float

Sharpening level (0.0-1.0). Applies to Redefine model only.

denoise float

Denoising level (0.0-1.0). Applies to Redefine model only.

detail float

Detail recovery level (0.0-1.0). Applies to Recovery V2 model only.

VideoCreativeUpscaleRequest#

video_url string* required

URL of the video to upscale

prompt string

Optional text prompt guiding the detail Astra 2 generates. When set, the input video is limited to 450 frames.

creativity float

How much new detail and texture Astra 2 invents. 0.0 stays faithful to the source, 1.0 is maximally creative. Default value: 0.5

realism float

Bias generated detail toward photorealism (0.0-1.0).

sharp float

Output sharpness. 0.0 softens, 0.5 is neutral passthrough, 1.0 applies strong sharpening. Defaults to Topaz's neutral 0.5.

upscale_factor float

Requested upscale factor (e.g. 2.0 doubles width and height). Note: Astra 2 snaps to its own supported output resolutions (typically 4K when upscaling) and may override the requested target. Billing is based on the delivered resolution. Default value: 2

target_fps integer

Target FPS for frame interpolation. If set, frame interpolation will be enabled.

H264_output boolean

Whether to use H264 codec for output video. Default is H265.

ImageCreativeUpscaleRequest#

image_url string* required

Url of the image to be upscaled

model ModelEnum

Creative (Bloom) upscaling model. Bloom 2 is the latest and most capable; Bloom creatively upscales and transforms AI-generated images; Bloom Realism biases the added detail toward photorealism. Default value: "Bloom 2"

Possible enum values: Bloom 2, Bloom, Bloom Realism

upscale_factor float

Factor to upscale the image by (e.g. 2.0 doubles width and height) Default value: 2

autoprompt boolean

Enable automatic prompt generation. Applies to Bloom 2 only; Topaz defaults it to true when omitted.

creativity integer

Creativity level (1-9). Higher values produce more creative/hallucinated details. Applies to Bloom 2 only.

color_preservation boolean

Preserve the source image's colors in the output. Applies to Bloom 2 only.

crop_to_fill boolean
output_format OutputFormatEnum

Output format of the upscaled image. Default value: "jpeg"

Possible enum values: jpeg, png