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

# Smallest AI

> Text-to-speech service using Smallest AI's WebSocket streaming API

## Overview

Smallest AI provides real-time text-to-speech synthesis through a WebSocket-based integration with their Waves API. The service supports configurable voice parameters, multiple languages, and handles interruptions by reconnecting the WebSocket.

<CardGroup cols={2}>
  <Card title="Smallest AI TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.smallest.tts.html">
    Complete API reference for all parameters and methods
  </Card>

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

## Installation

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

## Prerequisites

1. **Smallest AI Account**: Sign up at [Smallest AI](https://www.smallest.ai/)
2. **API Key**: Generate an API key from your account dashboard

Set the following environment variable:

```bash theme={null}
export SMALLEST_API_KEY=your_api_key
```

## Configuration

<ParamField path="api_key" type="str" required>
  Smallest AI API key for authentication.
</ParamField>

<ParamField path="base_url" type="str" default="wss://api.smallest.ai">
  Base WebSocket URL for the Smallest API. Override for custom or proxied
  deployments.
</ParamField>

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

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

### Settings

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

| Parameter     | Type              | Default          | Description                                                                                                               |
| ------------- | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `model`       | `str`             | `lightning-v3.1` | Model identifier: `lightning-v2` or `lightning-v3.1`. Model changes require WebSocket reconnection. *(Init-only setting)* |
| `voice`       | `str`             | `sophia`         | Voice identifier.                                                                                                         |
| `language`    | `Language \| str` | `Language.EN`    | Language code for synthesis.                                                                                              |
| `speed`       | `float`           | `None`           | Speech speed multiplier. When `None`, uses API defaults.                                                                  |
| `consistency` | `float`           | `None`           | Consistency level for voice generation (0-1). Only supported by `lightning-v2`. When `None`, uses API defaults.           |
| `similarity`  | `float`           | `None`           | Similarity level for voice generation (0-1). Only supported by `lightning-v2`. When `None`, uses API defaults.            |
| `enhancement` | `int`             | `None`           | Enhancement level for voice generation (0-2). Only supported by `lightning-v2`. When `None`, uses API defaults.           |

<Note>
  `None` values use the Smallest AI API defaults. The `consistency`,
  `similarity`, and `enhancement` parameters are only supported by the
  `lightning-v2` model.
</Note>

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.smallest import SmallestTTSService

tts = SmallestTTSService(
    api_key=os.getenv("SMALLEST_API_KEY"),
    settings=SmallestTTSService.Settings(
        voice="sophia",
    ),
)
```

### With Voice Customization

```python theme={null}
from pipecat.transcriptions.language import Language

tts = SmallestTTSService(
    api_key=os.getenv("SMALLEST_API_KEY"),
    settings=SmallestTTSService.Settings(
        voice="sophia",
        language=Language.ES,
        speed=1.2,
    ),
)
```

### Using Lightning V2 Model

```python theme={null}
from pipecat.services.smallest.tts import SmallestTTSModel

tts = SmallestTTSService(
    api_key=os.getenv("SMALLEST_API_KEY"),
    settings=SmallestTTSService.Settings(
        model=SmallestTTSModel.LIGHTNING_V2,
        voice="sophia",
        consistency=0.7,
        similarity=0.8,
        enhancement=1,
    ),
)
```

### Updating Settings at Runtime

Voice settings can be changed mid-conversation using `TTSUpdateSettingsFrame`:

```python theme={null}
from pipecat.frames.frames import TTSUpdateSettingsFrame
from pipecat.services.smallest.tts import SmallestTTSSettings

await task.queue_frame(
    TTSUpdateSettingsFrame(
        delta=SmallestTTSSettings(
            voice="new_voice",
            speed=1.1,
        )
    )
)
```

<Tip>
  Changing the `model` setting will trigger a WebSocket reconnection, which may
  cause a brief interruption in service.
</Tip>

## Notes

* **WebSocket streaming**: The service uses WebSocket connections for real-time streaming. The connection is automatically managed and will reconnect if interrupted.
* **Keepalive**: The service sends periodic keepalive messages (every 30 seconds) to prevent idle timeouts on the WebSocket connection.
* **Model-specific parameters**: The `consistency`, `similarity`, and `enhancement` parameters are only effective when using the `lightning-v2` model. They are ignored by `lightning-v3.1`.
* **Language support**: Supports multiple languages including Arabic, Bengali, German, English, Spanish, French, Gujarati, Hebrew, Hindi, Italian, Kannada, Marathi, Dutch, Polish, Russian, and Tamil.

## Event Handlers

Smallest AI TTS supports the standard [service connection events](/api-reference/server/events/service-events):

| Event                 | Description                          |
| --------------------- | ------------------------------------ |
| `on_connected`        | Connected to Smallest AI WebSocket   |
| `on_disconnected`     | Disconnected from Smallest WebSocket |
| `on_connection_error` | WebSocket connection error occurred  |

```python theme={null}
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Smallest AI")
```