Setup

Install the client:

npm install @fal-ai/client

Set your API key (option 1 - environment variable, safer):

export FAL_KEY="your_key_here"

Set your API key (option 2 - in code):

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

fal.config({
  credentials: "your_key_here",
});

Generate Image from Text

Endpoint: fal-ai/nano-banana-2

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

const result = await fal.subscribe("fal-ai/nano-banana-2", {
  input: {
    prompt: "a cat sitting on the moon",
  },
});

console.log(result.data.images[0].url);

Edit Image

Endpoint: fal-ai/nano-banana-2/edit

Pass one or multiple image URLs plus a prompt describing the edit.

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

const result = await fal.subscribe("fal-ai/nano-banana-2/edit", {
  input: {
    prompt: "make the background a sunset",
    image_urls: ["https://example.com/my-photo.png"],
  },
});

console.log(result.data.images[0].url);

Multiple images example:

const result = await fal.subscribe("fal-ai/nano-banana-2/edit", {
  input: {
    prompt: "make a photo of the man driving the car down the coastline",
    image_urls: [
      "https://example.com/person.png",
      "https://example.com/car.png",
    ],
  },
});

Optional Settings

These work on both endpoints. Add them to the input object.

Setting	Default	Options
`aspect_ratio`	`"auto"`	auto, 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16
`resolution`	`"1K"`	0.5K, 1K, 2K, 4K
`output_format`	`"png"`	jpeg, png, webp
`num_images`	`1`	any integer
`seed`	random	any integer (for reproducible results)
`safety_tolerance`	`"4"`	1 (strictest) to 6 (least strict)
`limit_generations`	`true`	true/false - limits to 1 generation per prompt round
`enable_web_search`	not set	true/false - lets model use web info

Response Format

Both endpoints return the same structure:

{
  "images": [
    {
      "url": "https://...",
      "content_type": "image/png",
      "file_name": "output.png",
      "file_size": 123456,
      "width": 1024,
      "height": 1024
    }
  ],
  "description": ""
}

Access in code: result.data.images[0].url

Queue System (Advanced)

For more control instead of using fal.subscribe.

Submit:

const { request_id } = await fal.queue.submit("fal-ai/nano-banana-2", {
  input: { prompt: "a cat on the moon" },
  webhookUrl: "https://optional.webhook.url/for/results",
});

Check status:

const status = await fal.queue.status("fal-ai/nano-banana-2", {
  requestId: "your-request-id",
  logs: true,
});

Get result:

const result = await fal.queue.result("fal-ai/nano-banana-2", {
  requestId: "your-request-id",
});

File Upload

If you need to upload a local file to get a URL for editing:

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

const file = new File([buffer], "photo.png", { type: "image/png" });
const url = await fal.storage.upload(file);
// now use this url in image_urls

The client also auto-uploads if you pass a binary object like a File or Blob.