> ## Documentation Index
> Fetch the complete documentation index at: https://fal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> fal has two developer products. Model APIs run hosted models through an API key. fal Serverless deploys your own Python apps and models on fal GPUs.
> To call a hosted model, start with the [Quick Start](https://fal.ai/docs/documentation/quickstart.md) and the [Model APIs overview](https://fal.ai/docs/documentation/model-apis/overview.md).
> To deploy your own model with fal Serverless, start with these pages:
> - [Introduction to Serverless](https://fal.ai/docs/documentation/serverless/index.md): What fal Serverless is and the three ways to deploy on it.
> - [Installation & Setup](https://fal.ai/docs/documentation/development/getting-started/installation.md): Install the fal CLI with `pip install fal` and authenticate.
> - [Quick Start](https://fal.ai/docs/documentation/development/getting-started/quick-start.md): Build a Hello World app, test it with `fal run`, and ship it with `fal deploy`.
> - [App Lifecycle](https://fal.ai/docs/documentation/development/app-lifecycle.md): How a `fal.App` goes from code to running runners.
> - [Define Your Endpoints](https://fal.ai/docs/documentation/development/endpoints-overview.md): Structure the API endpoints that your app exposes.
> - [Deploy to Production](https://fal.ai/docs/documentation/deployment/deploy-to-production.md): Persistent URLs, authentication modes, and automatic scaling.
> - [Machine Types](https://fal.ai/docs/documentation/deployment/machine-types.md): Available GPU and CPU machine types and how to choose one.
> - [Pricing](https://fal.ai/docs/documentation/serverless/pricing.md): Per-second billing and the runner states that are billed.
> - [Scaling Parameter Reference](https://fal.ai/docs/documentation/deployment/scale-your-application.md): Parameters that control runners, concurrency, and scale to zero.
> - [Optimizing Cold Starts](https://fal.ai/docs/documentation/serverless/optimizations/optimize-cold-starts.md): Causes of cold starts and ways to make them shorter.
> - [Examples](https://fal.ai/docs/examples/index.md): Complete Serverless apps for image, video, audio, 3D, realtime, and multi-GPU workloads.
> - [Migrating to fal](https://fal.ai/docs/documentation/development/migrating-to-fal.md): Guides to move an existing Docker server or an app from another platform to fal.
> fal Serverless deploys need access that the fal team approves for each account. Request access at https://fal.ai/dashboard/serverless-get-started.

# Client Setup

> Install and configure the fal client library

The fal client is the easiest way to call models on fal. It handles [authentication](https://fal.ai/docs/documentation/model-apis/authentication.md), retries, and provides a clean API for all [inference methods](https://fal.ai/docs/documentation/model-apis/inference.md). 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](https://fal.ai/docs/documentation/model-apis/inference/proxy-setup.md) on your server, which attaches the key before forwarding to fal. Both approaches are covered in the [Configuration](#configuration) section below.

## Installation

```bash npm theme={null}
npm install @fal-ai/client
```

```bash yarn theme={null}
yarn add @fal-ai/client
```

```bash pnpm theme={null}
pnpm add @fal-ai/client
```

```bash bun theme={null}
bun add @fal-ai/client
```

```bash pip theme={null}
pip install fal-client
```

```bash Flutter theme={null}
flutter pub add fal_client
```

```swift Swift Package theme={null}
.package(url: "https://github.com/fal-ai/fal-swift.git", from: "0.5.6")
```

```groovy Gradle (Java) theme={null}
implementation 'ai.fal.client:fal-client:0.7.1'
```

```xml Maven (Java) theme={null}
<dependency>
    <groupId>ai.fal.client</groupId>
    <artifactId>fal-client</artifactId>
    <version>0.7.1</version>
</dependency>
```

```groovy Gradle (Kotlin) theme={null}
implementation 'ai.fal.client:fal-client-kotlin:0.7.1'
```

```xml Maven (Kotlin) theme={null}
<dependency>
    <groupId>ai.fal.client</groupId>
    <artifactId>fal-client-kotlin</artifactId>
    <version>0.7.1</version>
</dependency>
```

> [!NOTE]
>
> **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:

```bash theme={null}
export FAL_KEY="your-api-key-here"
```

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

```python Python theme={null}
import fal_client

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

```javascript JavaScript theme={null}
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:

```python Python theme={null}
import os
os.environ["FAL_KEY"] = "your-api-key-here"

import fal_client
```

```javascript JavaScript theme={null}
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:

```bash theme={null}
npm install @fal-ai/server-proxy
```

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

```typescript theme={null}
import { createRouteHandler } from "@fal-ai/server-proxy/nextjs";

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

Then configure the client in your frontend code:

```typescript theme={null}
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](https://fal.ai/docs/documentation/model-apis/inference/proxy-setup.md)**
>
> 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:

```python Python theme={null}
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"])
```

```python Python (async) theme={null}
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())
```

```javascript JavaScript theme={null}
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);
```

```swift Swift theme={null}
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)
    }
}
```

```java Java theme={null}
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()
);
```

```kotlin Kotlin theme={null}
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)
    }
}
```

```dart Dart (Flutter) theme={null}
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

The Python client supports [backup domains](https://fal.ai/docs/documentation/model-apis/inference/reliability.md#backup-domains) for HTTP inference requests when a primary connection fails.
See that guide for the domain mappings, connection timeouts, and coverage limits.

> **[JavaScript / TypeScript](https://fal-ai.github.io/fal-js/reference)**
>
> API docs and [GitHub repo](https://github.com/fal-ai/fal-js)

> **[Python](https://fal-ai.github.io/fal/client)**
>
> API docs and [GitHub repo](https://github.com/fal-ai/fal)

> **[Swift (iOS)](https://swiftpackageindex.com/fal-ai/fal-swift/documentation/falclient)**
>
> API docs and [GitHub repo](https://github.com/fal-ai/fal-swift)

> **[Java / Kotlin](https://fal-ai.github.io/fal-java/fal-client/index.html)**
>
> API docs and [GitHub repo](https://github.com/fal-ai/fal-java)

> **[Dart (Flutter)](https://pub.dev/documentation/fal_client/latest)**
>
> API docs and [GitHub repo](https://github.com/fal-ai/fal-dart)

> **[Community](https://discord.gg/fal-ai)**
>
> Get help on Discord