Skip to main content
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
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"
})
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

​
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 { route } from "@fal-ai/server-proxy/nextjs";

export const { GET, POST, PUT, DELETE } = route;
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"])

​
Client Methods

MethodHow it worksUses Queue
run()Direct synchronous callNo
subscribe()Blocks until result, polls automaticallyYes
submit()Returns immediately, poll or use webhooksYes
stream()Progressive output via SSENo
realtime()WebSocket connectionNo
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