Fal

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 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.

import { generateImage } from 'ai';

const { image } = await generateImage({
  model: 'openai/gpt-image-2.5-sunburst',
  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:

pnpm add ai

npm install ai

yarn add ai

bun add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the AI Gateway provider documentation for configuration and the model catalog for available models.

The current Gateway provider list 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:

pnpm add ai @ai-sdk/fal

npm install ai @ai-sdk/fal

yarn add ai @ai-sdk/fal

bun add ai @ai-sdk/fal

Set your Fal API credential in the FAL_API_KEY environment variable:

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.

Provider Instance

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

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

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

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

  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 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().

Basic Usage

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

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.

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.

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

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)

Refer to the Fal AI model documentation 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.

Transcription Models

You can create models that call the Fal transcription API using the .transcription() factory method.

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

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.

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

Speech Models

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

Basic Usage

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

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.