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.