Client Setup

The fal client is the easiest way to call models on fal. It handles authentication, retries, and provides a clean API for all inference methods. Official clients are available for Python, JavaScript/TypeScript, Swift, Java, Kotlin, and Dart, and they all expose the same core methods (subscribe, submit, run, stream). How you configure the client depends on where your code runs. In a server-side environment like a Python script, a Node.js backend, or a serverless function, you set your FAL_KEY as an environment variable and the client picks it up automatically. In a client-side environment like a React app running in the browser, you cannot use the API key directly because browser source code is visible to anyone. Instead, the fal client routes requests through a lightweight proxy on your server, which attaches the key before forwarding to fal. Both approaches are covered in the Configuration section below.

Installation

npm install @fal-ai/client

yarn add @fal-ai/client

pnpm add @fal-ai/client

bun add @fal-ai/client

pip install fal-client

flutter pub add fal_client

.package(url: "https://github.com/fal-ai/fal-swift.git", from: "0.5.6")

implementation 'ai.fal.client:fal-client:0.7.1'

<dependency>
    <groupId>ai.fal.client</groupId>
    <artifactId>fal-client</artifactId>
    <version>0.7.1</version>
</dependency>

implementation 'ai.fal.client:fal-client-kotlin:0.7.1'

<dependency>
    <groupId>ai.fal.client</groupId>
    <artifactId>fal-client-kotlin</artifactId>
    <version>0.7.1</version>
</dependency>

Java Async Support — If your code relies on asynchronous operations via CompletableFuture or Future, use the ai.fal.client:fal-client-async artifact instead.

Configuration

Server-side (Python, Node.js)

The simplest path. Set your API key as an environment variable and the client picks it up automatically:

export FAL_KEY="your-api-key-here"

No additional configuration is needed. The client reads FAL_KEY from the environment on import:

import fal_client

result = fal_client.run("fal-ai/flux/schnell", arguments={
    "prompt": "a sunset"
})

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

const result = await fal.run("fal-ai/flux/schnell", {
  input: { prompt: "a sunset" }
});

In some environments (serverless functions, containers) you may not have access to shell environment variables. In those cases you can set credentials explicitly in code:

import os
os.environ["FAL_KEY"] = "your-api-key-here"

import fal_client

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

fal.config({
  credentials: "your-api-key-here"
});

Client-side (Browser, React, Next.js)

When building web apps, your API key cannot live in browser code because browser source is visible to anyone. Instead, the fal client routes requests through a lightweight proxy on your server that attaches the key before forwarding to fal. Your API key stays on the server, and all client methods (subscribe, submit, run, stream) work transparently through the proxy. The setup has two parts: create a proxy route on your server and point the client at it. Here is the quickest path using Next.js:

npm install @fal-ai/server-proxy

Create app/api/fal/proxy/route.ts (App Router):

import { createRouteHandler } from "@fal-ai/server-proxy/nextjs";

export const { GET, POST, PUT } = createRouteHandler();

Then configure the client in your frontend code:

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

fal.config({
  proxyUrl: "/api/fal/proxy"
});

const result = await fal.subscribe("fal-ai/flux/schnell", {
  input: { prompt: "a sunset" }
});

Make sure FAL_KEY is set as an environment variable on your server. The proxy reads it from the environment, just like the server-side setup above.

Proxy Setup

Pages Router, Vercel, Express, custom frameworks, and how the proxy works under the hood

Making Your First Call

Once configured, you can call any model:

import fal_client

result = fal_client.subscribe("fal-ai/flux/schnell", arguments={
    "prompt": "a futuristic cityscape at sunset",
    "image_size": "landscape_16_9"
})

print(result["images"][0]["url"])

import asyncio
import fal_client

async def main():
    result = await fal_client.subscribe_async(
        "fal-ai/flux/schnell",
        arguments={
            "prompt": "a futuristic cityscape at sunset",
            "image_size": "landscape_16_9"
        },
    )
    print(result["images"][0]["url"])

asyncio.run(main())

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

const result = await fal.subscribe("fal-ai/flux/schnell", {
  input: {
    prompt: "a futuristic cityscape at sunset",
    image_size: "landscape_16_9"
  }
});

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

import FalClient

let result = try await fal.subscribe(
    to: "fal-ai/flux/schnell",
    input: [
        "prompt": "a futuristic cityscape at sunset",
        "image_size": "landscape_16_9"
    ],
    includeLogs: true
) { update in
    if case let .inProgress(logs) = update {
        print(logs)
    }
}

import ai.fal.client.*;
import ai.fal.client.queue.*;

var fal = FalClient.withEnvCredentials();

var result = fal.subscribe("fal-ai/flux/schnell",
    SubscribeOptions.<JsonObject>builder()
        .input(Map.of(
            "prompt", "a futuristic cityscape at sunset",
            "image_size", "landscape_16_9"
        ))
        .logs(true)
        .resultType(JsonObject.class)
        .build()
);

import ai.fal.client.kt

val fal = createFalClient()

val result = fal.subscribe("fal-ai/flux/schnell",
    mapOf(
        "prompt" to "a futuristic cityscape at sunset",
        "image_size" to "landscape_16_9"
    ),
    options = SubscribeOptions(logs = true)
) { update ->
    if (update is QueueStatus.InProgress) {
        println(update.logs)
    }
}

import 'package:fal_client/fal_client.dart';

final fal = FalClient.withCredentials("FAL_KEY");

final output = await fal.subscribe("fal-ai/flux/schnell",
  input: {
    "prompt": "a futuristic cityscape at sunset",
    "image_size": "landscape_16_9"
  },
  logs: true,
  onQueueUpdate: (update) { print(update); }
);

print(output.data);

Client Methods

Method	How it works	Uses Queue
`run()`	Direct synchronous call	No
`subscribe()`	Blocks until result, polls automatically	Yes
`submit()`	Returns immediately, poll or use webhooks	Yes
`stream()`	Progressive output via SSE	No
`realtime()`	WebSocket connection	No

Every method in the Python SDK has an async counterpart with an _async suffix (e.g., subscribe_async, submit_async, run_async, stream_async, realtime_async). Use these when working with asyncio.

API References and Support

JavaScript / TypeScript

API docs and GitHub repo

Python

API docs and GitHub repo

Swift (iOS)

API docs and GitHub repo

Java / Kotlin

API docs and GitHub repo

Dart (Flutter)

API docs and GitHub repo

Community

Get help on Discord

​Installation

​Configuration

​Server-side (Python, Node.js)

​Client-side (Browser, React, Next.js)

Proxy Setup

​Making Your First Call

​Client Methods

​API References and Support

JavaScript / TypeScript

Python

Swift (iOS)

Java / Kotlin

Dart (Flutter)

Community

Installation

Configuration

Server-side (Python, Node.js)

Client-side (Browser, React, Next.js)

Making Your First Call

Client Methods

API References and Support