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

# fal

> Image generation service implementation using fal's fast SDXL models

## Overview

`FalImageGenService` provides high-speed image generation capabilities using fal's optimized Stable Diffusion XL models. It supports various image sizes, formats, and generation parameters with a focus on fast inference and low-latency image creation.

<CardGroup cols={2}>
  <Card title="Fal Image Gen API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.fal.image.html">
    Pipecat's API methods for fal image generation integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/getting-started/04-sync-speech-and-image.py">
    Browse examples using fal image generation
  </Card>

  <Card title="fal Documentation" icon="book" href="https://fal.ai/docs">
    Official fal API documentation and model guides
  </Card>

  <Card title="fal Platform" icon="image" href="https://fal.ai/">
    Access fast SDXL models and manage API keys
  </Card>
</CardGroup>

## Installation

To use fal image generation services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[fal]"
```

## Prerequisites

### fal Account Setup

Before using fal image generation services, you need:

1. **fal Account**: Sign up at [fal Platform](https://fal.ai/)
2. **API Key**: Generate an API key from your account dashboard
3. **Model Selection**: Choose from available fast SDXL models
4. **HTTP Session**: Configure aiohttp session for image downloading

### Required Environment Variables

* `FAL_KEY`: Your fal API key for authentication

## Configuration

<ParamField path="params" type="InputParams" deprecated>
  Input parameters for image generation configuration. *Deprecated in v0.0.105.
  Use `settings=FalImageGenService.Settings(...)` instead.*
</ParamField>

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  HTTP client session for downloading generated images.
</ParamField>

<ParamField path="model" type="str" default="fal-ai/fast-sdxl" deprecated>
  The fal model to use for image generation. *Deprecated in v0.0.105. Use
  `settings=FalImageGenService.Settings(model=...)` instead.*
</ParamField>

<ParamField path="key" type="str" default="None">
  Optional API key for fal. If provided, sets the `FAL_KEY` environment
  variable.
</ParamField>

<ParamField path="settings" type="FalImageGenService.Settings" default="None">
  Runtime-configurable generation settings. See [Settings](#settings) below.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `FalImageGenService.Settings(...)`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter               | Type          | Default     | Description                                                             |
| ----------------------- | ------------- | ----------- | ----------------------------------------------------------------------- |
| `model`                 | `str`         | `NOT_GIVEN` | Fal model identifier. *(Inherited from base settings.)*                 |
| `seed`                  | `int \| None` | `NOT_GIVEN` | Random seed for reproducible generation. If `None`, uses a random seed. |
| `num_inference_steps`   | `int`         | `NOT_GIVEN` | Number of inference steps for generation.                               |
| `num_images`            | `int`         | `NOT_GIVEN` | Number of images to generate.                                           |
| `image_size`            | `str \| dict` | `NOT_GIVEN` | Image dimensions as a string preset or dict with `width`/`height` keys. |
| `expand_prompt`         | `bool`        | `NOT_GIVEN` | Whether to automatically expand/enhance the prompt.                     |
| `enable_safety_checker` | `bool`        | `NOT_GIVEN` | Whether to enable content safety filtering.                             |
| `format`                | `str`         | `NOT_GIVEN` | Output image format.                                                    |

<Note>
  `NOT_GIVEN` values are omitted from the request, letting the service use its
  own defaults (`"fal-ai/fast-sdxl"` for model, `8` for num\_inference\_steps,
  `"square_hd"` for image\_size, etc.). Only parameters that are explicitly set
  are included.
</Note>

## Usage

### Basic Setup

```python theme={null}
import aiohttp
from pipecat.services.fal import FalImageGenService

async with aiohttp.ClientSession() as session:
    image_gen = FalImageGenService(
        aiohttp_session=session,
        key=os.getenv("FAL_KEY"),
        settings=FalImageGenService.Settings(
            image_size="landscape_16_9",
        ),
    )
```

### With Custom Settings

```python theme={null}
image_gen = FalImageGenService(
    aiohttp_session=session,
    key=os.getenv("FAL_KEY"),
    settings=FalImageGenService.Settings(
        model="fal-ai/fast-sdxl",
        image_size={"width": 1024, "height": 768},
        num_inference_steps=12,
        seed=42,
        enable_safety_checker=True,
    ),
)
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Notes

* **Environment variable**: If the `key` constructor parameter is provided, it sets the `FAL_KEY` environment variable automatically.
* **HTTP session required**: You must provide an `aiohttp.ClientSession` for downloading the generated images from fal's URLs.
* **Image size presets**: The `image_size` parameter accepts string presets (e.g., `"square_hd"`, `"landscape_16_9"`) or a dictionary with explicit `width` and `height` values.