# fal.ai

The fal.ai adapter calls hosted models for images, video, live video, motion clips, 3D models, speech, transcription, music, and sound effects. It has no text chat and no tools.

The quick setup below generates an image on your server and shows it in React. For a full app, see the [media example](https://github.com/TanStack/ai/tree/main/examples/ts-react-media).

## 1. Install

```sh
npm i @tanstack/ai-fal
```

## 2. Set the API key

Create a key at [fal.ai](https://fal.ai). Put it in the environment of your server:

```bash
FAL_KEY=your-fal-api-key
```

All fal adapters read `FAL_KEY`. To pass the key in code, set `apiKey` in the config:

```typescript
import { falImage } from "@tanstack/ai-fal";

const adapter = falImage("fal-ai/nano-banana-pro", {
  apiKey: process.env.FAL_KEY!,
});
```

## 3. Generate an image on the server

Add a `POST` route at `/api/generate/image`:

```typescript
import {
  generateImage,
  generationParamsFromRequest,
  toServerSentEventsResponse,
} from "@tanstack/ai";
import { falImage } from "@tanstack/ai-fal";

export async function POST(request: Request) {
  const { input, threadId } = await generationParamsFromRequest("image", request);
  if (typeof input.prompt !== "string") {
    return new Response("Send a text prompt.", { status: 400 });
  }

  const stream = generateImage({
    adapter: falImage("fal-ai/nano-banana-pro"),
    prompt: input.prompt,
    threadId,
    stream: true,
  });

  return toServerSentEventsResponse(stream);
}
```

## 4. Show the image

```tsx
import { fetchServerSentEvents, useGenerateImage } from "@tanstack/ai-react";

export function ImageGenerator() {
  const { generate, result, isLoading, error } = useGenerateImage({
    connection: fetchServerSentEvents("/api/generate/image"),
    threadId: "image-studio",
  });

  return (
    <div>
      <button
        onClick={() => generate({ prompt: "A futuristic cityscape at sunset" })}
        disabled={isLoading}
      >
        {isLoading ? "Generating..." : "Generate"}
      </button>
      {error && <p role="alert">{error.message}</p>}
      {result?.images.map((image, index) => (
        <img
          key={index}
          src={image.url || `data:image/png;base64,${image.b64Json}`}
          alt="Generated image"
        />
      ))}
    </div>
  );
}
```

Click the button. The image shows up below it. For the other frameworks, see [Generation Hooks](../media/generation-hooks).

## Model options

Each fal model has its own options. Write the model id as a string literal, and TypeScript completes `size` and `modelOptions` for that model:

```typescript
import { generateImage } from "@tanstack/ai";
import { falImage } from "@tanstack/ai-fal";

const result = await generateImage({
  adapter: falImage("fal-ai/z-image/turbo"),
  prompt: "A serene mountain landscape",
  threadId: "thread-1",
  numberOfImages: 1,
  size: "landscape_16_9",
  modelOptions: {
    acceleration: "high",
    enable_prompt_expansion: true,
  },
});

console.log(result.images);
```

- Pass the id directly, not through a `string` variable. A variable loses the types of the model.
- Any string works as a model id. A model that is newer than the fal SDK types runs, but has no autocomplete.

For the `size` formats, see [Image sizes](#image-sizes).

## Video

Video runs as a job. `generateVideo()` starts the job, and `getVideoJobStatus()` reads its status:

```typescript
import { generateVideo, getVideoJobStatus } from "@tanstack/ai";
import { falVideo } from "@tanstack/ai-fal";

const adapter = falVideo("fal-ai/kling-video/v2.6/pro/text-to-video");

const job = await generateVideo({
  adapter,
  prompt: "A timelapse of a flower blooming",
  threadId: "thread-1",
  size: "16:9",
  duration: "5",
});

const status = await getVideoJobStatus({ adapter, jobId: job.jobId });

console.log(status.status); // "pending" | "processing" | "completed"
```

To animate an image, use an image-to-video model and set the start image in `modelOptions`:

```typescript
import { generateVideo } from "@tanstack/ai";
import { falVideo } from "@tanstack/ai-fal";

const job = await generateVideo({
  adapter: falVideo("fal-ai/kling-video/v2.6/pro/image-to-video"),
  prompt: "Animate this scene with gentle wind",
  threadId: "thread-1",
  duration: "5",
  modelOptions: {
    start_image_url: "https://example.com/image.jpg",
    generate_audio: true,
  },
});

console.log(job.jobId);
```

The `duration` values of each model are in [Video durations](#video-durations). To poll from a React component, see [Video Generation](../media/video-generation).

## 3D models

`fal3DModel()` turns an image, a text prompt, or an existing mesh into a 3D model file. Like video, it runs as a job. With `wait: true`, `generate3DModel()` returns the finished model:

```typescript
import { generate3DModel } from "@tanstack/ai";
import { fal3DModel } from "@tanstack/ai-fal";

const model = await generate3DModel({
  adapter: fal3DModel("fal-ai/hunyuan-3d/v3.1/pro/image-to-3d"),
  prompt: [
    {
      type: "image",
      source: { type: "url", value: "https://example.com/concept/chest.png" },
    },
  ],
  threadId: "thread-1",
  wait: true,
  modelOptions: { face_count: 40_000, enable_pbr: true },
});

console.log(model.url, model.format); // "https://...glb", "glb"
```

3D model generation is experimental. How the prompt reaches fal:

- Text goes to `prompt`.
- Image parts go to the image field of the model, for example `input_image_url` on Hunyuan3D.
- One `model3d` part goes to the mesh field. See [Mesh input models](#mesh-input-models).
- A part that the model cannot use throws before the job starts.

`url` on the result is the best GLB. `files` holds every mesh file, each with a `role` such as `"rigged"`, and the texture files with the role `"texture"`. To stream the job to React, and for a full pipeline, see [3D Model Generation](../media/3d-model-generation).

## Live video

`falLiveVideo("minimax/h3-max/director")` starts a live video stream that you can steer. The browser connects through a proxy on your server. See [Live Generation](../media/live-generation#fal-h3-max-director).

## Motion

`falMotion` makes a skeletal animation clip (FBX) from a prompt. It runs as a job. `generateMotion()` submits it, and `getMotionJobStatus()` reads its status:

```typescript
import { generateMotion, getMotionJobStatus } from "@tanstack/ai";
import { falMotion } from "@tanstack/ai-fal";

const adapter = falMotion("fal-ai/hunyuan-motion");

const { jobId } = await generateMotion({
  adapter,
  prompt: "A heavy two-handed overhead axe swing with a slow wind-up",
  threadId: "orc-attacks",
  duration: 3,
  modelOptions: {
    seed: 42,
    guidance_scale: 7,
  },
});

const status = await getMotionJobStatus({ adapter, jobId });

console.log(status.status); // "pending" | "processing" | "completed" | "failed"
console.log(status.motion?.assets[0]?.url); // The FBX, when the job is complete
```

The options:

| Option | Values | Default |
| --- | --- | --- |
| `duration` | 0.5 to 12 seconds | 5 |
| `modelOptions.seed` | Any integer. Send the same seed again to repeat a take. | Random |
| `modelOptions.guidance_scale` | 1 to 10. A higher value follows the prompt more closely. | 5 |
| `modelOptions.output_format` | `"fbx"` for an FBX file, `"dict"` for raw JSON motion data | `"fbx"` |

What you get back:

- The `fbx_file` output becomes an asset with `format: "fbx"`. With the default `output_format`, fal returns only this file.
- If fal also returns `motion_json`, it becomes an asset with `format: "json"`.
- fal names every file `hy_motion_000.fbx`. Save each clip under your own name.
- `seed` is the seed that fal used. `usage` holds the billed units.
- fal does not return clip length, frame rate, or joint names. The FBX holds an SMPL-H skeleton (52 bones, root bone `Pelvis`) at 30 fps, plus a skinned mannequin mesh. Root motion is in the `Pelvis` bone. Retarget the skeleton to your rig in your engine.
- fal takes no character or skeleton input.
- File URLs expire after the media expiry time in your fal account. Download the files and store them.

`cancelMotionJob()` uses the fal queue cancel. fal removes a queued job. A running job can still finish. fal refuses a cancel for a completed job.

See [Motion Generation](../media/motion-generation) for streaming, agent tools, and engine import.

## Speech

`falSpeech` gets the audio from the fal CDN and returns it as base64:

```typescript
import { generateSpeech } from "@tanstack/ai";
import { falSpeech } from "@tanstack/ai-fal";

const result = await generateSpeech({
  adapter: falSpeech("fal-ai/gemini-3.1-flash-tts"),
  text: "[warm, enthusiastic] Welcome to TanStack AI! [pause] Let's build something great.",
  threadId: "thread-1",
  voice: "Kore",
});

console.log(result.format, result.contentType);
```

`fal-ai/gemini-3.1-flash-tts` is the TTS model of Google. It supports 80+ languages. You can put speaker tags and style tags, such as `[pause]`, in the text. Its `modelOptions` have no autocomplete yet.

Other models put the voice in `modelOptions`:

```typescript
import { generateSpeech } from "@tanstack/ai";
import { falSpeech } from "@tanstack/ai-fal";

const result = await generateSpeech({
  adapter: falSpeech("fal-ai/elevenlabs/tts/eleven-v3"),
  text: "Welcome to TanStack AI.",
  threadId: "thread-1",
  modelOptions: {
    voice: "Rachel",
    stability: 0.5,
  },
});

console.log(result.audio); // Base64-encoded audio
```

See [Text-to-Speech](../media/text-to-speech).

## Transcription

```typescript
import { generateTranscription } from "@tanstack/ai";
import { falTranscription } from "@tanstack/ai-fal";

const result = await generateTranscription({
  adapter: falTranscription("fal-ai/whisper"),
  audio: "https://example.com/recording.mp3",
  language: "en",
  threadId: "thread-1",
});

console.log(result.text);
console.log(result.language);

// When the model returns timestamps, they are in result.segments
for (const segment of result.segments ?? []) {
  console.log(`[${segment.start}s to ${segment.end}s] ${segment.text}`);
}
```

`audio` takes a URL string, a `Blob`, a `File`, or an `ArrayBuffer`. The adapter wraps an `ArrayBuffer` in a `Blob` for the upload.

## Music and sound effects

`falAudio` returns a URL in `result.audio.url`. If you need the bytes, fetch the URL:

```typescript
import { generateAudio } from "@tanstack/ai";
import { falAudio } from "@tanstack/ai-fal";

const music = await generateAudio({
  adapter: falAudio("fal-ai/minimax-music/v2.6"),
  prompt: "City Pop, 80s retro, groovy synth bass, warm female vocal, 104 BPM, nostalgic urban night",
  threadId: "thread-1",
});

const sfx = await generateAudio({
  adapter: falAudio("fal-ai/elevenlabs/sound-effects/v2"),
  prompt: "Thunderclap with rain",
  threadId: "thread-1",
  duration: 5,
});

console.log(music.audio.url, sfx.audio.url);
```

Some music models take lyrics in `modelOptions`:

```typescript
import { generateAudio } from "@tanstack/ai";
import { falAudio } from "@tanstack/ai-fal";

const song = await generateAudio({
  adapter: falAudio("fal-ai/diffrhythm"),
  prompt: "An upbeat electronic track with synths",
  threadId: "thread-1",
  modelOptions: {
    lyrics: "[verse]\nHello world\n[chorus]\nLa la la",
  },
});

console.log(song.audio.url);
```

See [Audio Generation](../media/audio-generation).

## Files

`falFiles` uploads media to fal storage, so a request can point to the file by URL. fal storage is upload-only. See [Files API](../advanced/files-api).

## Models and options

fal has hundreds of models. These are popular picks. Any fal model id works.

### Image models

| Model | Description |
|-------|-------------|
| `fal-ai/nano-banana-pro` | Fast, high-quality images, up to 4K |
| `fal-ai/flux-2/klein/9b` | Realistic images, clear text |
| `fal-ai/z-image/turbo` | A very fast 6B-parameter model |
| `xai/grok-imagine-image` | xAI images with prompt enhancement |

### Video models

| Model | Mode | Description |
|-------|------|-------------|
| `fal-ai/kling-video/v2.6/pro/text-to-video` | Text-to-video | High-quality text-to-video |
| `fal-ai/kling-video/v2.6/pro/image-to-video` | Image-to-video | Animate images with Kling |
| `fal-ai/veo3.1` | Text-to-video | Google Veo text-to-video |
| `fal-ai/veo3.1/image-to-video` | Image-to-video | Google Veo image-to-video |
| `xai/grok-imagine-video/text-to-video` | Text-to-video | xAI video from text |
| `xai/grok-imagine-video/image-to-video` | Image-to-video | xAI video from an image |
| `fal-ai/ltx-2/text-to-video/fast` | Text-to-video | Fast text-to-video |
| `fal-ai/ltx-2/image-to-video/fast` | Image-to-video | Fast image-to-video |

### 3D model endpoints

`fal3DModel()` knows these families. Write the id as a string literal, and TypeScript completes `modelOptions` and narrows the prompt parts. Any other fal 3D id also works, with no types.

| Family | Ids | Input |
|--------|-----|-------|
| Hunyuan3D 3.1 | `fal-ai/hunyuan-3d/v3.1/pro/image-to-3d`, `.../pro/text-to-3d`, `.../rapid/image-to-3d`, `.../rapid/text-to-3d` | One image, or text |
| Hunyuan3D 3 | `fal-ai/hunyuan3d-v3/image-to-3d`, `.../text-to-3d` | One image, or text |
| Hunyuan3D 2 | `fal-ai/hunyuan3d/v2` (also `/turbo`, `/mini`, `/mini/turbo`, `/multi-view`, `/multi-view/turbo`) | One image. Multi-view takes its views in `modelOptions`. |
| Meshy 7.1 | `meshy/v7.1/image-to-3d`, `meshy/v7.1/multi-image-to-3d`, `meshy/v7.1/text-to-3d` | Image, images, or text |
| Meshy 6 | `fal-ai/meshy/v6/image-to-3d`, `fal-ai/meshy/v6/text-to-3d`, `fal-ai/meshy/v6-preview/text-to-3d` | Image, or text |
| TRELLIS | `fal-ai/trellis`, `fal-ai/trellis/multi`, `fal-ai/trellis-2` | One or more images |
| Tripo | `tripo3d/tripo/v2.5/image-to-3d`, `tripo3d/tripo/v2.5/multiview-to-3d` | One image. Multi-view takes its views in `modelOptions`. |
| Rodin | `fal-ai/hyper3d/rodin`, `fal-ai/hyper3d/rodin/v2` | Images and text |
| SAM 3 | `fal-ai/sam-3/3d-objects`, `fal-ai/sam-3/3d-body` | An image, and text for objects |

#### Mesh input models

These models take an existing mesh. Send the mesh as one `model3d` part. The adapter puts its URL in the mesh field:

| Model | What it does | Mesh field | Other prompt parts |
|-------|--------------|------------|--------------------|
| `meshy/v7/retexture` | New textures from a style image or text, up to 8k | `model_url` | One image (`image_style_url`), or text (`text_style_prompt`) |
| `fal-ai/trellis-2/retexture` | New textures from a reference image | `mesh_url` | One image |
| `tripo3d/tripo/remesh` | A new mesh with fewer faces, with the textures baked on | `mesh_url` | None. Set `face_limit` in `modelOptions`. |

For a low-poly mesh with quad faces, set `topology: 'quad'` and `target_polycount` in the `modelOptions` of `meshy/v7.1/image-to-3d`.

### Live models

| Model | Description |
|-------|-------------|
| `minimax/h3-max/director` | A live stream that you can steer. Use `falLiveVideo()` with `generateLiveVideo()`. |

### Motion models

| Model | Description |
|-------|-------------|
| `fal-ai/hunyuan-motion` | Hunyuan Motion 1B. About $0.08 per generation. |
| `fal-ai/hunyuan-motion/fast` | Hunyuan Motion 0.46B, faster. About $0.06 per generation. |

Both take the same options and return FBX. Use them with `falMotion()` and `generateMotion()`. Prices are from the fal model pages and can change.

### Text-to-speech models

| Model | Description |
|-------|-------------|
| `fal-ai/gemini-3.1-flash-tts` | Google TTS with 80+ languages and style tags |
| `fal-ai/elevenlabs/tts/eleven-v3` | ElevenLabs v3, expressive, several voices |
| `fal-ai/elevenlabs/tts/turbo-v2.5` | ElevenLabs, low latency |
| `fal-ai/minimax/speech-2.6-hd` | MiniMax HD speech |
| `fal-ai/minimax/speech-2.6-turbo` | MiniMax, low latency |
| `fal-ai/kokoro/american-english` | Kokoro. Also `british-english`, `french`, `spanish`, `italian`, `japanese`, `mandarin-chinese`, `hindi`, `brazilian-portuguese` |
| `fal-ai/inworld-tts` | Inworld TTS-1.5 Max |
| `fal-ai/chatterbox/text-to-speech/multilingual` | Chatterbox, many languages |
| `fal-ai/dia-tts` | Dia, expressive dialogue |
| `fal-ai/orpheus-tts` | Orpheus, open source |
| `fal-ai/f5-tts` | F5-TTS, voice cloning |
| `fal-ai/vibevoice/7b` | VibeVoice 7B, conversation |

### Transcription models

| Model | Description |
|-------|-------------|
| `fal-ai/whisper` | OpenAI Whisper on fal |
| `fal-ai/wizper` | A faster Whisper with word timestamps |
| `fal-ai/speech-to-text/turbo` | Fast speech-to-text with speaker labels |
| `fal-ai/elevenlabs/speech-to-text` | ElevenLabs speech-to-text |

### Music and audio models

| Model | Mode | Description |
|-------|------|-------------|
| `fal-ai/minimax-music/v2.6` | Music | MiniMax Music 2.6, vocals and instruments from a prompt |
| `fal-ai/minimax-music/v2.5` | Music | MiniMax Music 2.5 |
| `fal-ai/minimax-music/v2` | Music | MiniMax Music v2, takes `lyrics_prompt` |
| `fal-ai/diffrhythm` | Music | DiffRhythm, prompt and lyrics |
| `fal-ai/lyria2` | Music | Google Lyria 2 |
| `fal-ai/stable-audio-25/text-to-audio` | Music or audio | Stability AI Stable Audio 2.5 |
| `fal-ai/mmaudio-v2/text-to-audio` | Audio | MMAudio v2 |
| `fal-ai/elevenlabs/sound-effects/v2` | Sound effects | ElevenLabs sound effects |
| `fal-ai/beatoven/sound-effect-generation` | Sound effects | Beatoven sound effects |
| `fal-ai/thinksound` | Audio | Thinksound audio |

Some very new models, for example `fal-ai/gemini-3.1-flash-tts`, `fal-ai/minimax-music/v2.6`, and `fal-ai/beatoven/sound-effect-generation`, are not in the type map of `@fal-ai/client` yet. They work as plain string ids, with no autocomplete for `modelOptions`.

## Advanced

### Image sizes

`size` maps to `image_size`, or to `aspect_ratio` and `resolution`:

| Form | `size` | Sent to fal as |
|--------|---------|---------|
| Named | `"landscape_16_9"` | `image_size: "landscape_16_9"` |
| Width x height | `"1536x1024"` | `image_size: "1536x1024"` |
| Ratio and resolution | `"16:9_4K"` | `aspect_ratio: "16:9"`, `resolution: "4K"` |
| Ratio only | `"16:9"` | `aspect_ratio: "16:9"` |

Named sizes change by model.

### Video durations

`duration` gets its type for each model from the `EndpointTypeMap` of `@fal-ai/client`. Popular models also have `availableDurations()` and `snapDuration()`, for a UI slider:

| Model | `duration` type | `availableDurations()` |
| --- | --- | --- |
| `fal-ai/kling-video/v1.6/{standard,pro}/text-to-video`, `fal-ai/kling-video/v2.6/pro/{text,image}-to-video` | `"5"` or `"10"` | discrete |
| `fal-ai/kling-video/v3/pro/{text,image}-to-video` | `"3"` to `"15"` | discrete |
| `fal-ai/ltx-2.3/{text,image}-to-video` | `6`, `8`, or `10` | discrete |
| `fal-ai/ltx-2.3/{text,image}-to-video/fast` | `6` to `20`, in steps of 2 | discrete |
| `fal-ai/veo3.1`, `fal-ai/veo3.1/fast` (and `/image-to-video`), `fal-ai/veo3` (and `/image-to-video`) | `"4s"`, `"6s"`, or `"8s"` | discrete |
| `fal-ai/wan-25-preview/text-to-video` | `"5"` or `"10"` | discrete |
| `fal-ai/minimax/video-01` | not accepted | `{ kind: "none" }` |
| `fal-ai/hunyuan-video-v1.5/text-to-video` | not accepted (uses `num_frames`) | `{ kind: "none" }` |

`@fal-ai/client` has no types for Veo and Kling 1.6. For these models, `duration` takes any value. Use `snapDuration()` to get a valid one.

```typescript
import { generateVideo } from "@tanstack/ai";
import { falVideo } from "@tanstack/ai-fal";

const adapter = falVideo("fal-ai/veo3.1");
adapter.availableDurations(); // { kind: "discrete", values: ["4s", "6s", "8s"] }
adapter.snapDuration(7); // "6s"

await generateVideo({
  adapter,
  prompt: "A timelapse of a city skyline at dusk",
  threadId: "thread-1",
  duration: adapter.snapDuration(7),
});
```

Other models still get the `duration` type from the SDK when the endpoint has the field. For these models, `availableDurations()` returns `{ kind: "none" }`.

### Configuration

Each factory takes an optional `FalClientConfig`:

- `apiKey`: your fal key. If you do not set a config, the adapter reads `FAL_KEY`.
- `proxyUrl`: a proxy URL on your server, for calls from the browser.
- `fetch`: a custom `fetch` for the fal requests. The adapter wraps it to read the billed units.

```typescript
import { falImage } from "@tanstack/ai-fal";

const adapter = falImage("fal-ai/nano-banana-pro", {
  apiKey: process.env.FAL_KEY!,
  proxyUrl: "https://your-server.com/api/fal/proxy",
});
```

### Live video proxy

`generateLiveVideo()` returns the WMA app id on `result.model` (`fal-ai/minimax-h3-max-director`). In the browser:

- Open that id with `wma(live.model)` through a proxy on your server. The proxy attaches `FAL_KEY`.
- Do not send `live.token` as `Key` credentials.
- In the proxy, call `allowedFalLiveVideoProxyTarget()`. It lets the proxy forward only to WMA `/ice`, `/session`, `/session/heartbeat`, and Director `/ice`.

### API reference

Each factory takes `model` first and an optional `config` (`apiKey`, `proxyUrl`, `fetch`). Without `apiKey`, it reads `FAL_KEY`.

| Factory | Returns | Use it with |
| --- | --- | --- |
| `falImage(model, config?)` | `FalImageAdapter` | `generateImage()` |
| `falVideo(model, config?)` | `FalVideoAdapter` | `generateVideo()`, `getVideoJobStatus()` |
| `falLiveVideo(model, config?)` / `createFalLiveVideo(model, apiKey, config?)` | `FalLiveVideoAdapter` | `generateLiveVideo()` |
| `falSpeech(model, config?)` | `FalSpeechAdapter` | `generateSpeech()`. The audio comes back as base64 in `result.audio`. |
| `falTranscription(model, config?)` | `FalTranscriptionAdapter` | `generateTranscription()` |
| `falAudio(model, config?)` | `FalAudioAdapter` | `generateAudio()`. The result has a URL at `result.audio.url`. |
| `fal3DModel(model, config?)` | `Fal3DModelAdapter` | `generate3DModel()`, `get3DModelJobStatus()`. Experimental. |
| `falFiles(config?)` | `FalFilesAdapter` | The [Files API](../advanced/files-api) |

Helpers:

- `getFalApiKeyFromEnv()`: reads `FAL_KEY`. Throws if it is not set.
- `configureFalClient(config?)`: configures `@fal-ai/client`. The adapter constructors call it for you. It sets the credentials from the API key, and the proxy when you set `proxyUrl`.
