fal-ai/smart-resize

Smart image resize to arbitrary dimensions, powered by Nano Banana Pro with vision-LLM-guided prompting for composition-aware recomposition. Crop, cropping, resize ads.

Learn more about Smart Resize

Inference

Commercial use

Partner

Schema

LLMs

Playground API Examples

About

Resize an image to one or more exact target dimensions. Smart Resize uses nano-banana-pro internally: for each requested <width>x<height> the endpoint picks the smallest nano-banana-pro preset that fully covers the target, regenerates the image with an adaptive prompt, and then center-crops it to the exact requested dimensions so the output is pixel-perfect.

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

Migrate to @fal-ai/client

The @fal-ai/serverless-client package has been deprecated in favor of @fal-ai/client. Please check the migration guide for more information.

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/smart-resize", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png",
    target_sizes: ["1024x1024", "1920x1080", "768x1344"]
  },
  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"
});

Protect your API Key

When running code on the client-side (e.g. in a browser, mobile app or GUI applications), make sure to not expose your FAL_KEY. Instead, use a server-side proxy to make requests to the API. For more information, check out our server-side integration guide.

3. Queue#

Long-running requests

For long-running requests, such as training jobs or models with slower inference times, it is recommended to check the Queue status and rely on Webhooks instead of blocking while waiting for the result.

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/smart-resize", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png",
    target_sizes: ["1024x1024", "1920x1080", "768x1344"]
  },
  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/smart-resize", {
  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/smart-resize", {
  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);

Auto uploads

The client will auto-upload the file for you if you pass a binary object (e.g. File, Data).

Read more about file handling in our file upload guide.

5. Schema#

Input#

image_url string* required

The URL of the source image to resize.

target_sizes list<string>* required

The list of target dimensions to generate, each written as <width>x<height> (e.g. "1920x1080"). One output image is produced per target size (multiplied by num_images_per_size). The endpoint internally picks the smallest nano-banana-pro preset that fully covers each target so the final image is a pixel-perfect match with no upscaling.

prompt string

Optional extra instruction that is forwarded to nano-banana-pro alongside the auto-generated resize prompt. Leave empty to let the model preserve the original image content as closely as possible. Default value: ""

num_images_per_size integer

The number of nano-banana-pro variants to produce for each target size. The response images list will contain len(target_sizes) * num_images_per_size images in total. Default value: 1

resolution ResolutionEnum

Hint for the minimum resolution tier to use internally. The smart-resize algorithm may pick a higher tier automatically when the requested target size is too large for this tier. This field does not affect the final output dimensions — those come from target_sizes. Default value: "1K"

Possible enum values: 1K, 2K, 4K

output_format OutputFormatEnum

The output image format. Default value: "png"

Possible enum values: jpeg, png, webp

safety_tolerance SafetyToleranceEnum

The safety tolerance level applied to the inner nano-banana-pro /edit calls. Higher numbers loosen safety filtering. Default value: "4"

Possible enum values: 1, 2, 3, 4, 5, 6

seed integer

Optional random seed forwarded to the inner nano-banana-pro /edit calls for reproducibility. The same seed is used for every target size when set.

sync_mode boolean

When True, the response contains data URIs in place of CDN URLs so the client can decode the images without an extra HTTP request. Adds latency for large outputs.

{
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png",
  "target_sizes": [
    "1024x1024",
    "1920x1080",
    "768x1344"
  ],
  "prompt": "",
  "num_images_per_size": 1,
  "resolution": "1K",
  "output_format": "png",
  "safety_tolerance": "4"
}

Output#

images list<ImageFile>* required

All generated images, flattened across every target size. Order matches the order of results below: the first num_images_per_size entries correspond to target_sizes[0] and so on.

description string* required

The description of the generated images.

results list<SmartResizeResult>* required

Per-target-size breakdown with the requested width/height and the nano-banana-pro (aspect_ratio, resolution) preset that was used internally.

{
  "images": [
    {
      "file_name": "nano-banana-pro-edit-output.png",
      "content_type": "image/png",
      "url": "https://storage.googleapis.com/falserverless/example_outputs/nano-banana-pro-edit-output.png"
    }
  ],
  "description": "",
  "results": [
    {
      "images": [
        {
          "url": "",
          "content_type": "image/png",
          "file_name": "z9RV14K95DvU.png",
          "file_size": 4404019
        }
      ],
      "description": "",
      "aspect_ratio": "",
      "resolution": ""
    }
  ]
}

Other types#

SmartResizeResult#

images list<ImageFile>* required

The generated images.

description string* required

The description of the generated images.

width integer* required

The requested target width in pixels.

height integer* required

The requested target height in pixels.

aspect_ratio string* required

The nano-banana-pro aspect ratio that was used internally for this target size.

resolution string* required

The nano-banana-pro resolution tier that was used internally for this target size.

ImageFile#

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.

width integer

The width of the image

height integer

The height of the image

fal-ai/smart-resize

Table of contents

1. Calling the API

2. Authentication

3. Queue

4. Files

5. Schema

About

1. Calling the API#

Install the client#

Migrate to @fal-ai/client

Setup your API Key#

Submit a request#

2. Authentication#

API Key#

Protect your API Key

3. Queue#

Long-running requests

Submit a request#

Fetch request status#

Get the result#

4. Files#

Data URI (base64)#

Hosted files (URL)#

Uploading files#

Auto uploads

5. Schema#

Input#

Output#

Other types#

SmartResizeResult#

ImageFile#

Related Models