---
title: Fal
description: Learn how to use Fal with AI Gateway and the direct provider.
url: "https://ai-sdk.dev/providers/ai-sdk-providers/fal"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

[Fal AI](https://fal.ai/) provides a generative media platform for developers with lightning-fast inference capabilities. Their platform offers optimized performance for running diffusion models, with speeds up to 4x faster than alternatives.
Use [AI Gateway](/providers/ai-sdk-providers/ai-gateway) for the shared models shown below, served by Gateway's supported providers, or use `@ai-sdk/fal` to send requests directly to Fal. Gateway does not currently route requests to Fal.

```ts provider="fal" model="bfl/flux-pro-1.1"
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: "bfl/flux-pro-1.1",
  prompt: 'A sunlit mountain village in watercolor.',
});

console.log(image.base64);
```

## Using AI Gateway

The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install `ai`:

```bash
pnpm add ai
```

Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment:

```bash
export AI_GATEWAY_API_KEY=your_api_key_here
```

Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments).
See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models.

The current [Gateway provider list](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options#available-providers) does not include Fal as an inference provider. The Gateway tab calls models also available from Fal, but Gateway routes them through its supported inference providers. It does not send the request to Fal. Use the direct tab to call Fal; do not set `providerOptions.gateway.order` to an unsupported provider slug.

## Using `@ai-sdk/fal`

For direct access to Fal, install `ai` and `@ai-sdk/fal`:

```bash
pnpm add ai @ai-sdk/fal
```

Set your Fal API credential in the `FAL_API_KEY` environment variable:

```bash
export FAL_API_KEY=your_api_key_here
```

Use `@ai-sdk/fal` to authenticate with your Fal account and call its platform APIs directly. The Gateway alternative above uses a supported inference provider instead.

The following sections document the direct `@ai-sdk/fal` provider, including
its model factories and settings. Gateway model and feature availability can
differ.

## Provider Instance

You can import the default provider instance `fal` from `@ai-sdk/fal`:

```ts
import { fal } from '@ai-sdk/fal';
```

If you need a customized setup, you can import `createFal` and create a provider instance with your settings:

```ts
import { createFal } from '@ai-sdk/fal';

const fal = createFal({
  apiKey: 'your-api-key', // optional, defaults to FAL_API_KEY environment variable, falling back to FAL_KEY
  baseURL: 'custom-url', // optional
  headers: {
    /* custom headers */
  }, // optional
});
```

You can use the following optional settings to customize the Fal provider instance:

- **baseURL** *string*

  Use a different URL prefix for API calls, e.g. to use proxy servers.
  The default prefix is `https://fal.run`.

- **apiKey** *string | PromiseLike\<string> | (() => string | PromiseLike\<string>)*

  Pass a function to resolve credentials before each request, including when keys
  rotate. The function can return a string or a promise. Credential caching and
  refresh are managed by the function.

  API key that is being sent using the `Authorization` header.
  It defaults to the `FAL_API_KEY` environment variable, falling back to `FAL_KEY`.

- **headers** *Record\<string,string>*

  Custom headers to include in the requests.

- **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\<Response>*

  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
  You can use it as a middleware to intercept requests,
  or to provide a custom fetch implementation for e.g. testing.

## Image Models

You can create Fal image models using the `.image()` factory method.
For more on image generation with the AI SDK see [generateImage()](/docs/reference/ai-sdk-core/generate-image).

The provider downloads generated images from URLs returned by Fal using the
`fetch` option of `createFal`. On Node.js, pass a `guarded-fetch` transport
there to validate DNS results. See [Secure URL
Fetching](/docs/advanced/secure-url-fetching#opt-in-dns-protection-on-nodejs).

### Basic Usage

```ts
import { fal } from '@ai-sdk/fal';
import { generateImage } from 'ai';
import fs from 'fs';

const { image, providerMetadata } = await generateImage({
  model: fal.image('fal-ai/flux/dev'),
  prompt: 'A serene mountain landscape at sunset',
});

const filename = `image-${Date.now()}.png`;
fs.writeFileSync(filename, image.uint8Array);
console.log(`Image saved to ${filename}`);
```

Fal image models may return additional information for the images and the request.

Here are some examples of properties that may be set for each image

```js
providerMetadata.fal.images[0].nsfw; // boolean, image is not safe for work
providerMetadata.fal.images[0].width; // number, image width
providerMetadata.fal.images[0].height; // number, image height
providerMetadata.fal.images[0].contentType; // string, mime type of the image
```

### Model Capabilities

Fal offers many models optimized for different use cases. Here are a few popular examples. For a full list of models, see the [Fal AI Search Page](https://fal.ai/explore/search).

| Model                                          | Description                                                                                                                 | Sizes                                                             | Image Editing | Mask Input | Max Images Per Call |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------- | ---------- | ------------------- |
| `bria/text-to-image/3.2`                       | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/bria/text-to-image/base`               | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/bria/text-to-image/fast`               | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/bria/text-to-image/hd`                 | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/bytedance/dreamina/v3.1/text-to-image` | Dreamina showcases superior picture effects with improvements in aesthetics, precise and diverse styles, and rich details   | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/flux-general/image-to-image`           | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✗          | 1                   |
| `fal-ai/flux-general/inpainting`               | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✓          | 1                   |
| `fal-ai/flux-kontext-lora/text-to-image`       | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/flux-lora/image-to-image`              | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✗          | 1                   |
| `fal-ai/flux-lora/inpainting`                  | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✓          | 1                   |
| `fal-ai/flux-pro/kontext`                      | FLUX.1 Kontext \[pro] handles both text and reference images as inputs, enabling targeted edits and complex transformations | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✗          | 1                   |
| `fal-ai/flux-pro/kontext/max`                  | FLUX.1 Kontext \[max] with improved prompt adherence and typography generation                                              | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✗          | 1                   |
| `fal-ai/flux/dev/image-to-image`               | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✗          | 1                   |
| `fal-ai/flux/krea/image-to-image`              | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✗          | 1                   |
| `fal-ai/recraft/v3/text-to-image`              | SOTA in image generation with vector art and brand style capabilities                                                       | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/recraft/v3/image-to-image`             | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✗          | 1                   |
| `fal-ai/wan/v2.2-5b/text-to-image`             | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/wan/v2.2-a14b/text-to-image`           | High-resolution, photorealistic images with fine-grained detail                                                             | Accepted size or aspect ratio depends on the model and operation. | ✗             | ✗          | 1                   |
| `fal-ai/flux-2/edit`                           | Not declared                                                                                                                | Accepted size or aspect ratio depends on the model and operation. | ✓             | ✗          | 1                   |

Fal models support the following aspect ratios:

- 1:1 (square HD)
- 16:9 (landscape)
- 9:16 (portrait)
- 4:3 (landscape)
- 3:4 (portrait)
- 16:10 (1280x800)
- 10:16 (800x1280)
- 21:9 (2560x1080)
- 9:21 (1080x2560)

Key features of Fal models include:

- Up to 4x faster inference speeds compared to alternatives
- Optimized by the Fal Inference Engine™
- Support for real-time infrastructure
- Cost-effective scaling with pay-per-use pricing
- LoRA training capabilities for model personalization

#### Modify Image

Transform existing images using text prompts.

```ts
await generateImage({
  model: fal.image('fal-ai/flux-pro/kontext/max'),
  prompt: {
    text: 'Put a donut next to the flour.',
    images: [
      'https://v3.fal.media/files/rabbit/rmgBxhwGYb2d3pl3x9sKf_output.png',
    ],
  },
});
```

Images can also be passed as base64-encoded string, a `Uint8Array`, an `ArrayBuffer`, or a `Buffer`.
A mask can be passed as well

```ts
await generateImage({
  model: fal.image('fal-ai/flux-general/inpainting'),
  prompt: {
    text: 'Put a donut next to the flour.',
    images: [imageBuffer],
    mask: maskBuffer,
  },
});
```

### Provider Options

Fal image models support flexible provider options through the `providerOptions.fal` object. You can pass any parameters supported by the specific Fal model's API. Common options include:

- **imageUrl** - Reference image URL for image-to-image generation (deprecated, use `prompt.images` instead)
- **strength** - Controls how much the output differs from the input image
- **guidanceScale** - Controls adherence to the prompt (range: 1-20)
- **numInferenceSteps** - Number of denoising steps (range: 1-50)
- **enableSafetyChecker** - Enable/disable safety filtering
- **outputFormat** - Output format: 'jpeg' or 'png'
- **syncMode** - Wait for completion before returning response
- **acceleration** - Speed of generation: 'none', 'regular', or 'high'
- **safetyTolerance** - Content safety filtering level (1-6, where 1 is strictest)
- **useMultipleImages** - When true, converts multiple input images to `image_urls` array for models that support multiple images (e.g., fal-ai/flux-2/edit)

**Deprecation Notice**: snake\_case parameter names (e.g., `image_url`,
`guidance_scale`) are deprecated and will be removed in a future version.
Please use camelCase names (e.g., `imageUrl`, `guidanceScale`) instead.

Refer to the [Fal AI model documentation](https://fal.ai/models) for model-specific parameters.

### Advanced Features

Fal's platform offers several advanced capabilities:

- **Private Model Inference**: Run your own diffusion transformer models with up to 50% faster inference
- **LoRA Training**: Train and personalize models in under 5 minutes
- **Real-time Infrastructure**: Enable new user experiences with fast inference times
- **Scalable Architecture**: Scale to thousands of GPUs when needed

For more details about Fal's capabilities and features, visit the [Fal AI documentation](https://fal.ai/docs).

## Transcription Models

You can create models that call the [Fal transcription API](https://docs.fal.ai/guides/convert-speech-to-text)
using the `.transcription()` factory method.

The first argument is the model id without the `fal-ai/` prefix e.g. `wizper`.

```ts
const model = fal.transcription('wizper');
```

You can also pass additional provider-specific options using the `providerOptions` argument. For example, supplying the `batchSize` option will increase the number of audio chunks processed in parallel.

```ts {6}
import { transcribe } from 'ai';
import { fal, type FalTranscriptionModelOptions } from '@ai-sdk/fal';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: fal.transcription('wizper'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    fal: { batchSize: 10 } satisfies FalTranscriptionModelOptions,
  },
});
```

The following provider options are available:

- **language** *string | null*
  Language of the audio file. Defaults to 'en'. If set to null, the language will be automatically detected.
  Accepts ISO language codes like 'en', 'fr', 'zh', etc.
  Optional.

- **diarize** *boolean*
  Whether to diarize the audio file (identify different speakers).
  Defaults to true.
  Optional.

- **chunkLevel** *string*
  Level of the chunks to return. Either 'segment' or 'word'.
  Default value: "segment"
  Optional.

- **version** *string*
  Version of the model to use. All models are Whisper large variants.
  Default value: "3"
  Optional.

- **batchSize** *number*
  Batch size for processing.
  Default value: 64
  Optional.

- **numSpeakers** *number*
  Number of speakers in the audio file. If not provided, the number of speakers will be automatically detected.
  Optional.

### Model Capabilities

| Model     | Transcription | Streaming | Duration | Segments | Language |
| --------- | ------------- | --------- | -------- | -------- | -------- |
| `whisper` | ✓             | ✗         | ✓        | ✓        | ✓        |
| `wizper`  | ✓             | ✗         | ✓        | ✓        | ✓        |

## Speech Models

You can create models that call Fal text-to-speech endpoints using the `.speech()` factory method.

### Basic Usage

```ts
import { generateSpeech } from 'ai';
import { fal } from '@ai-sdk/fal';

const result = await generateSpeech({
  model: fal.speech('fal-ai/minimax/speech-02-hd'),
  text: 'Hello from the AI SDK!',
});
```

### Model Capabilities

| Model                                     | Description                                                                                                                                                           | Instructions |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `fal-ai/minimax/voice-clone`              | Clone a voice from a sample audio and generate speech from text prompts                                                                                               | ✗            |
| `fal-ai/minimax/voice-design`             | Design a personalized voice from a text description and generate speech from text prompts                                                                             | ✗            |
| `fal-ai/dia-tts/voice-clone`              | Clone dialog voices from a sample audio and generate dialogs from text prompts                                                                                        | ✗            |
| `fal-ai/minimax/speech-02-hd`             | Generate speech from text prompts and different voices                                                                                                                | ✗            |
| `fal-ai/minimax/speech-02-turbo`          | Generate fast speech from text prompts and different voices                                                                                                           | ✗            |
| `fal-ai/dia-tts`                          | Directly generates realistic dialogue from transcripts with audio conditioning for emotion control. Produces natural nonverbals like laughter and throat clearing     | ✗            |
| `resemble-ai/chatterboxhd/text-to-speech` | Generate expressive, natural speech with Resemble AI's Chatterbox. Features unique emotion control, instant voice cloning from short audio, and built-in watermarking | ✗            |

### Provider Options

Pass provider-specific options via `providerOptions.fal` depending on the model:

- **voice\_setting** *object*
  - `voice_id` (string): predefined voice ID
  - `speed` (number): 0.5–2.0
  - `vol` (number): 0–10
  - `pitch` (number): -12–12
  - `emotion` (enum): happy | sad | angry | fearful | disgusted | surprised | neutral
  - `english_normalization` (boolean)

- **audio\_setting** *object*
  Audio configuration settings specific to the model.

- **language\_boost** *enum*
  Chinese | Chinese,Yue | English | Arabic | Russian | Spanish | French | Portuguese | German | Turkish | Dutch | Ukrainian | Vietnamese | Indonesian | Japanese | Italian | Korean | Thai | Polish | Romanian | Greek | Czech | Finnish | Hindi | auto

- **pronunciation\_dict** *object*
  Custom pronunciation dictionary for specific words.

Model-specific parameters (e.g., `audio_url`, `prompt`, `preview_text`, `ref_audio_url`, `ref_text`) can be passed directly under `providerOptions.fal` and will be forwarded to the Fal API.

## Video Model Capabilities

| Model                | Image Input                                            | First Frame | Last Frame | Reference Images | Reference Video | Audio | Aspect Ratio                                           | Resolution                                                   | Duration                                               | FPS | Seed                                                   |
| -------------------- | ------------------------------------------------------ | ----------- | ---------- | ---------------- | --------------- | ----- | ------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------ | --- | ------------------------------------------------------ |
| `luma-dream-machine` | Conditional: Supported by the selected model endpoint. | ✗           | ✗          | ✗                | ✗               | ✗     | Conditional: Supported by the selected model endpoint. | Conditional: Configured with providerOptions.fal.resolution. | Conditional: Supported by the selected model endpoint. | ✗   | Conditional: Supported by the selected model endpoint. |
| `luma-ray-2`         | Conditional: Supported by the selected model endpoint. | ✗           | ✗          | ✗                | ✗               | ✗     | Conditional: Supported by the selected model endpoint. | Conditional: Configured with providerOptions.fal.resolution. | Conditional: Supported by the selected model endpoint. | ✗   | Conditional: Supported by the selected model endpoint. |
| `luma-ray-2-flash`   | Conditional: Supported by the selected model endpoint. | ✗           | ✗          | ✗                | ✗               | ✗     | Conditional: Supported by the selected model endpoint. | Conditional: Configured with providerOptions.fal.resolution. | Conditional: Supported by the selected model endpoint. | ✗   | Conditional: Supported by the selected model endpoint. |
| `minimax-video`      | Conditional: Supported by the selected model endpoint. | ✗           | ✗          | ✗                | ✗               | ✗     | Conditional: Supported by the selected model endpoint. | Conditional: Configured with providerOptions.fal.resolution. | Conditional: Supported by the selected model endpoint. | ✗   | Conditional: Supported by the selected model endpoint. |
| `minimax-video-01`   | Conditional: Supported by the selected model endpoint. | ✗           | ✗          | ✗                | ✗               | ✗     | Conditional: Supported by the selected model endpoint. | Conditional: Configured with providerOptions.fal.resolution. | Conditional: Supported by the selected model endpoint. | ✗   | Conditional: Supported by the selected model endpoint. |
| `hunyuan-video`      | Conditional: Supported by the selected model endpoint. | ✗           | ✗          | ✗                | ✗               | ✗     | Conditional: Supported by the selected model endpoint. | Conditional: Configured with providerOptions.fal.resolution. | Conditional: Supported by the selected model endpoint. | ✗   | Conditional: Supported by the selected model endpoint. |

## Provider Option Reference

The following option definitions are generated from the provider catalog.

| Operation     | Option                  | Description                                                                                                                                                                                                                    |
| ------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| image         | `imageUrl`              | imageUrl                                                                                                                                                                                                                       |
| image         | `maskUrl`               | maskUrl                                                                                                                                                                                                                        |
| image         | `guidanceScale`         | guidanceScale                                                                                                                                                                                                                  |
| image         | `numInferenceSteps`     | numInferenceSteps                                                                                                                                                                                                              |
| image         | `enableSafetyChecker`   | enableSafetyChecker                                                                                                                                                                                                            |
| image         | `outputFormat`          | outputFormat                                                                                                                                                                                                                   |
| image         | `syncMode`              | syncMode                                                                                                                                                                                                                       |
| image         | `strength`              | strength                                                                                                                                                                                                                       |
| image         | `acceleration`          | acceleration                                                                                                                                                                                                                   |
| image         | `safetyTolerance`       | safetyTolerance                                                                                                                                                                                                                |
| image         | `useMultipleImages`     | When true, converts multiple input images to `image_urls` array instead of `image_url` string.                                                                                                                                 |
| image         | `image_url`             | image\_url                                                                                                                                                                                                                     |
| image         | `mask_url`              | mask\_url                                                                                                                                                                                                                      |
| image         | `guidance_scale`        | guidance\_scale                                                                                                                                                                                                                |
| image         | `num_inference_steps`   | num\_inference\_steps                                                                                                                                                                                                          |
| image         | `enable_safety_checker` | enable\_safety\_checker                                                                                                                                                                                                        |
| image         | `output_format`         | output\_format                                                                                                                                                                                                                 |
| image         | `sync_mode`             | sync\_mode                                                                                                                                                                                                                     |
| image         | `safety_tolerance`      | safety\_tolerance                                                                                                                                                                                                              |
| speech        | `voice_setting`         | voice\_setting                                                                                                                                                                                                                 |
| speech        | `audio_setting`         | audio\_setting                                                                                                                                                                                                                 |
| speech        | `language_boost`        | language\_boost                                                                                                                                                                                                                |
| speech        | `pronunciation_dict`    | pronunciation\_dict                                                                                                                                                                                                            |
| transcription | `language`              | Language of the audio file. If set to null, the language will be automatically detected. Defaults to null. If translate is selected as the task, the audio will be translated to English, regardless of the language selected. |
| transcription | `diarize`               | Whether to diarize the audio file. Defaults to true.                                                                                                                                                                           |
| transcription | `chunkLevel`            | Level of the chunks to return. Either segment or word. Default value: "segment"                                                                                                                                                |
| transcription | `version`               | Version of the model to use. All of the models are the Whisper large variant. Default value: "3"                                                                                                                               |
| transcription | `batchSize`             | Default value: 64                                                                                                                                                                                                              |
| transcription | `numSpeakers`           | Number of speakers in the audio file. Defaults to null. If not provided, the number of speakers will be automatically detected.                                                                                                |
| video         | `loop`                  | loop                                                                                                                                                                                                                           |
| video         | `motionStrength`        | motionStrength                                                                                                                                                                                                                 |
| video         | `resolution`            | resolution                                                                                                                                                                                                                     |
| video         | `negativePrompt`        | negativePrompt                                                                                                                                                                                                                 |
| video         | `promptOptimizer`       | promptOptimizer                                                                                                                                                                                                                |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)