Run Nano Banana 2.1 AI Image Editor API on fal
Google's latest image generation and editing model, now available as an image editing API on fal. Edit, restyle, and combine images with natural language prompts, and keep people and products consistent across every result.
Overview
google/nano-banana-2.1/edit exposes Nano Banana 2.1 as an image editing endpoint. Provide up to 14 reference images with a text prompt, and the model applies targeted edits, restyles a scene, or fuses several images into one while preserving what you didn't ask to change.
In Google's words, Nano Banana 2.1 "outperforms our previous models across the board, with notable leaps in visual design, mask-based editing, and subject consistency to help you create more natural-looking images." An update to Nano Banana 2 (Gemini 3.1 Flash Image), it keeps Flash-level speed and cost efficiency while delivering significant improvements in visual quality, prompt adherence, character consistency, and text rendering. Google positions it as the more efficient counterpart to Nano Banana Pro.
The endpoint also accepts a video (including YouTube links) or a PDF as context, so you can create thumbnails, posters, and summary visuals from existing media.
This is the same underlying model as google/nano-banana-2.1, set up for editing rather than generating from scratch.
Pricing
Nano Banana 2.1 is billed on the tokens each request actually uses, as reported by Google. There are no flat per-image fees or surcharges for resolution, web search, or thinking; those settings only change how many tokens a request uses.
| Token type | Price per 1M tokens |
|---|
| Input (prompt text, images, and other media) | $1.764 |
| Output text and thinking | $8.823 |
| Output image | $35.294 |
The following table shows representative costs for one output image from a short prompt (about 100 tokens), excluding thinking and web search tokens:
| Output resolution | Text-to-image | Edit with two 1K input images |
|---|
| 1K | $0.040 | $0.044 |
| 2K | $0.059 | $0.063 |
| 4K | $0.134 | $0.138 |
This implies the following:
- Resolution drives cost. Google lists output images at about 1,120 tokens at 1K, 1,680 at 2K, and 3,780 at 4K, so a 4K image costs more than three times as much as a 1K image.
- Every input adds input tokens. Each input image is about 1,120 tokens, roughly $0.002, so 14 reference images add about $0.028. Video and PDF context is also billed as input tokens, so long videos and documents cost more.
- Thinking is billed as output text.
thinking_level defaults to medium; high uses more thinking tokens and costs more, and minimal costs less.
- Web search has no separate fee. Search results the model reads are billed as input tokens.
- Each image is billed separately. With
num_images above 1, each image is its own generation, so the prompt and every input are counted once per output image.
What it can do
Precise Edits from Natural Language
Describe what should change and what should stay the same. Swap backgrounds, change clothing or materials, add or remove objects, adjust lighting, or restyle an entire scene without any masking. Google calls this semantic masking and recommends prompts like: "Using the provided image, change only the [specific element] to [new element/description]. Keep everything else in the image exactly the same, preserving the original style, lighting, and composition."
Mask- and Sketch-Based Edits
Mask-based editing is one of Google's headline improvements in 2.1. To target a region visually, paint, outline, or scribble over it on the input image, then describe what should replace the marked area. There is no separate mask parameter: the markings travel with the image. You can also upload a rough sketch and ask the model to refine it into a finished image.
Subject Consistency
Keep people and products recognizable across edits and new scenes. Google reports clear gains over Nano Banana 2 and Nano Banana Pro in single- and multi-character consistency, with support for up to 4 characters and up to 10 high-fidelity objects in a single request.
Multi-Image Fusion
Combine up to 14 reference images in one request: place a product in a new setting, dress a person in an outfit from another photo, or compose a group shot from separate portraits.
Video and PDF as Context
Pass video_url (a video file up to 15 MB, or a YouTube URL) or pdf_url (a PDF up to 15 MB) to ground the result in existing media. Google suggests video-to-image for "high-quality video thumbnails, cinematic posters, summary infographics, or new artwork inspired by a video scene." When you provide either one, image_urls becomes optional.
Full Generation Controls
Edits support the same controls as text-to-image: 1K, 2K, or 4K output, aspect ratios from 8:1 to 1:8, thinking levels, web search grounding, and system prompts. With aspect_ratio left at auto, the model chooses the output shape, usually matching your input image.
Quick Start
Install the client
npm install --save @fal-ai/client
Set your API key
export FAL_KEY="YOUR_API_KEY"
Basic image edit
import { fal } from "@fal-ai/client";
const result = await fal.subscribe("google/nano-banana-2.1/edit", {
input: {
prompt:
"Change only the background to a rainy Tokyo street at night. Keep the person and their pose exactly the same.",
image_urls: ["https://your-image-url.com/photo.png"],
},
logs: true,
onQueueUpdate: (update) => {
if (update.status === "IN_PROGRESS") {
update.logs.map((log) => log.message).forEach(console.log);
}
},
});
console.log(result.data.images[0].url);
Combine multiple references
import { fal } from "@fal-ai/client";
const result = await fal.subscribe("google/nano-banana-2.1/edit", {
input: {
prompt:
"Show the woman from the first image wearing the jacket from the second image, sitting in the cafe from the third image. Keep her face and hairstyle unchanged.",
image_urls: [
"https://your-image-url.com/person.png",
"https://your-image-url.com/jacket.png",
"https://your-image-url.com/cafe.png",
],
resolution: "2K",
thinking_level: "high",
},
});
console.log(result.data.images[0].url);
Mask-based edit
import { fal } from "@fal-ai/client";
const result = await fal.subscribe("google/nano-banana-2.1/edit", {
input: {
prompt:
"Replace the area painted in red with a tall potted fiddle-leaf fig. Keep the rest of the room unchanged and remove the red paint.",
image_urls: ["https://your-image-url.com/room-with-red-mask.png"],
},
});
console.log(result.data.images[0].url);
Thumbnail from a video
import { fal } from "@fal-ai/client";
const result = await fal.subscribe("google/nano-banana-2.1/edit", {
input: {
prompt:
"Create a bold thumbnail for this video featuring the presenter from the image, with the headline 'I TRIED IT FOR 30 DAYS'",
image_urls: ["https://your-image-url.com/presenter.png"],
video_url: "https://www.youtube.com/watch?v=VIDEO_ID",
aspect_ratio: "16:9",
},
});
console.log(result.data.images[0].url);
API Reference
| Parameter | Type | Default | Description |
|---|
prompt | string | required | Text description of the edit to apply (3 to 50,000 characters) |
image_urls | list of strings | [] | Up to 14 images to edit or use as references. Required unless video_url or pdf_url is set |
video_url | string | optional | Video to use as context: a video file URL (up to 15 MB) or a YouTube URL |
pdf_url | string | optional | PDF document to use as context (up to 15 MB) |
aspect_ratio | enum | auto | Output aspect ratio. auto lets the model choose, usually matching the input image. See the values below |
resolution | enum | 1K | 1K, 2K, or 4K |
num_images | integer | 1 | Number of edited images to generate, from 1 to 4 |
output_format | enum | png | jpeg, png, or webp |
thinking_level | enum | medium | minimal, medium, or high. Higher levels use more thinking tokens |
enable_web_search | boolean | false | Grounds the generation in live Google Search results |
system_prompt | string | "" | Optional system instruction that steers style and persona for the whole request |
limit_generations | boolean | true | Experimental. When true, returns one image per generation and ignores prompt instructions about image count. Set to false to let the model return additional images and text |
safety_tolerance | enum | 4 | Moderation strictness, from 1 (most strict) to 6 (least strict) |
sync_mode | boolean | false | Returns images as data URIs directly; output excluded from request history |
Aspect ratios and resolutions
| Category | Values |
|---|
| Automatic | auto |
| Landscape | 21:9, 16:9, 3:2, 4:3, 5:4 |
| Square | 1:1 |
| Portrait | 4:5, 3:4, 2:3, 9:16 |
| Extreme | 4:1, 1:4, 8:1, 1:8 |
| Resolution | Approximate size |
|---|
1K (default) | 1 megapixel |
2K | 4 megapixels |
4K | 16 megapixels |
The 512px (0.5K) option from Nano Banana 2 is not available on Nano Banana 2.1.
Output
{
"images": [
{
"url": "https://v3b.fal.media/files/...",
"content_type": "image/png",
"file_name": "output.png",
"width": 1024,
"height": 1024
}
],
"description": ""
}
description holds any text the model returns alongside the images. It is usually empty unless limit_generations is false.
Using the Queue API
For production workloads or longer-running edits, submit requests asynchronously and retrieve results via webhook or polling.
// Submit
const { request_id } = await fal.queue.submit("google/nano-banana-2.1/edit", {
input: {
prompt: "...",
image_urls: ["https://your-image-url.com/photo.png"],
},
webhookUrl: "https://your-server.com/webhook",
});
// Check status
const status = await fal.queue.status("google/nano-banana-2.1/edit", {
requestId: request_id,
logs: true,
});
// Fetch result
const result = await fal.queue.result("google/nano-banana-2.1/edit", {
requestId: request_id,
});
The endpoint accepts public URLs or base64 data URIs for images, video, and PDFs. Browser-only blob: URLs are not supported. For files that are not publicly accessible, upload them first using the fal storage API:
import { fal } from "@fal-ai/client";
const file = new File([imageBuffer], "photo.png", { type: "image/png" });
const url = await fal.storage.upload(file);
// Use the returned URL in image_urls, video_url, or pdf_url
The client will also auto-upload binary objects (File, Blob, Buffer) if you pass them directly.
Use Cases
Product photography and recontextualization -- Place products in new scenes, swap backgrounds, or update props while keeping labels and details intact.
Character-consistent content -- Keep up to four people consistent across a series of images for storyboards, comics, and campaigns.
Virtual try-on -- Show a garment from one image on a person from another.
Targeted retouching -- Mark a region or describe it in words, and change only that area.
Style transfer -- Re-render a photo in a new artistic style while keeping its content.
Thumbnails and posters from media -- Turn a video or PDF into a thumbnail, poster, or summary infographic.
To learn more, see Google DeepMind's Nano Banana 2.1 model card and Google's Gemini API documentation.
Benchmarks
Results from Google's human side-by-side evaluations (Elo, higher is better), as published in the Nano Banana 2.1 model card:
| Editing benchmark | Nano Banana 2.1 (Thinking) | Nano Banana 2.1 (No Thinking) | Nano Banana 2 (Thinking) | Nano Banana Pro |
|---|
| General editing | 1026 | 980 | 938 | 939 |
| Single-character consistency | 1028 | 1021 | 981 | 991 |
| Multi-character consistency | 1106 | 1068 | 978 | 1011 |
| Mask/ink-based editing | 1049 | 1042 | 965 | 927 |
| Product consistency | 1024 | 981 | 955 | 965 |
| Stylization | 1062 | 1036 | 991 | 990 |
| Multi-reference editing | 1066 | 1041 | 988 | 989 |
See the model card for confidence intervals and methodology.
Tips for Best Results
- Say what stays the same. Name the elements to preserve, not just the change.
- Refer to images by position. For example, "the person in the first image" and "the jacket in the second image".
- Use thinking for complex edits. Set
thinking_level to high for multi-reference compositions. In Google's evaluations, thinking improved every editing benchmark.
- Clean up markings. For mask or sketch edits, ask the model to remove the marks; Google notes that ink can occasionally persist in the output.
- Describe pose changes explicitly. Google notes rare cases where a subject's pose carries over from the input image.
- Small text: Use 2K or 4K. Google notes that small text can render blurry at 1K.
Differences from the Text-to-Image Endpoint
| Feature | google/nano-banana-2.1/edit | google/nano-banana-2.1 |
|---|
| Input images | Up to 14 via image_urls | Not used |
| Video and PDF context | Yes | No |
| Default aspect ratio | auto (usually matches the input) | auto (chosen from the prompt) |
| Use case | Edit, combine, or restyle existing images | Generate from scratch |
| Pricing | Same token rates; each input adds input tokens | Same token rates |
google/nano-banana-2.1/edit
