> ## 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 (Wizper)

> Speech-to-text service implementation using Fal's Wizper API

## Overview

`FalSTTService` provides speech-to-text capabilities using Fal's Wizper API with Voice Activity Detection (VAD) to process only speech segments, optimizing API usage and improving response time for efficient transcription.

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

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-fal.py">
    Complete example with VAD integration
  </Card>

  <Card title="Fal Documentation" icon="book" href="https://fal.ai/models/fal-ai/wizper">
    Official Fal Wizper documentation and features
  </Card>

  <Card title="Fal Platform" icon="microphone" href="https://fal.ai/">
    Access API keys and Wizper models
  </Card>
</CardGroup>

## Installation

To use Fal services, install the required dependency:

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

## Prerequisites

### Fal Account Setup

Before using Fal STT 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 Access**: Ensure access to the Wizper transcription model

### Required Environment Variables

* `FAL_KEY`: Your Fal API key for authentication

## Configuration

### FalSTTService

<ParamField path="api_key" type="str" default="None">
  Fal API key. If not provided, uses `FAL_KEY` environment variable.
</ParamField>

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" default="None">
  Optional aiohttp ClientSession for HTTP requests. If not provided, a session
  will be created and managed internally.
</ParamField>

<ParamField path="task" type="str" default="transcribe">
  Task to perform (`"transcribe"` or `"translate"`).
</ParamField>

<ParamField path="chunk_level" type="str" default="segment">
  Level of chunking (`"segment"`).
</ParamField>

<ParamField path="version" type="str" default="3">
  Version of the Wizper model to use.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Audio sample rate in Hz. When `None`, uses the pipeline's configured sample
  rate.
</ParamField>

<ParamField path="params" type="FalSTTService.InputParams" default="None" deprecated>
  Configuration parameters for the Wizper API. *Deprecated in v0.0.105. Use
  `settings=FalSTTService.Settings(...)` instead.*
</ParamField>

<ParamField path="settings" type="FalSTTService.Settings" default="None">
  Runtime-configurable settings for the STT service. See [Settings](#settings)
  below.
</ParamField>

<ParamField path="ttfs_p99_latency" type="float" default="FAL_TTFS_P99">
  P99 latency from speech end to final transcript in seconds. Override for your
  deployment.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `FalSTTService.Settings(...)`. These can be updated mid-conversation with `STTUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default       | Description                                                        |
| ---------- | ----------------- | ------------- | ------------------------------------------------------------------ |
| `model`    | `str`             | `None`        | STT model identifier. *(Inherited from base STT settings.)*        |
| `language` | `Language \| str` | `Language.EN` | Language of the audio input. *(Inherited from base STT settings.)* |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.fal.stt import FalSTTService

stt = FalSTTService(
    api_key=os.getenv("FAL_KEY"),
)
```

### With Custom Parameters

```python theme={null}
from pipecat.services.fal.stt import FalSTTService
from pipecat.transcriptions.language import Language

stt = FalSTTService(
    api_key=os.getenv("FAL_KEY"),
    task="transcribe",
    version="3",
    settings=FalSTTService.Settings(
        language=Language.ES,
    ),
)
```

### Translation Mode

```python theme={null}
stt = FalSTTService(
    api_key=os.getenv("FAL_KEY"),
    task="translate",
    settings=FalSTTService.Settings(
        language=Language.FR,
    ),
)
```

<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

* **Segmented processing**: `FalSTTService` inherits from `SegmentedSTTService`, which buffers audio during speech (detected by VAD) and sends complete segments for transcription. This means it does not provide interim results -- only final transcriptions after each speech segment.
* **Translation support**: Set `task="translate"` to translate audio into English, regardless of the input language.
* **Wizper versions**: The `version` parameter selects the underlying Whisper model version. Version `"3"` is the default and recommended for best accuracy.