Smallest AI

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.

Smallest AI TTS API Reference

Complete API reference for all parameters and methods

Example Implementation

Complete example with WebSocket streaming

Installation

uv add "pipecat-ai[smallest]"

Prerequisites

Smallest AI Account: Sign up at Smallest AI
API Key: Generate an API key from your account dashboard

Set the following environment variable:

export SMALLEST_API_KEY=your_api_key

Configuration

api_key

str

required

Smallest AI API key for authentication.

base_url

str

default:"wss://api.smallest.ai"

Base WebSocket URL for the Smallest API. Override for custom or proxied deployments.

sample_rate

int

default:"None"

Output audio sample rate in Hz. When None, uses the pipeline’s configured sample rate.

settings

SmallestTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

Settings

Runtime-configurable settings passed via the settings constructor argument using SmallestTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See 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.

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

Usage

Basic Setup

from pipecat.services.smallest import SmallestTTSService

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

With Voice Customization

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

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:

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,
        )
    )
)

Changing the model setting will trigger a WebSocket reconnection, which may cause a brief interruption in service.

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:

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

@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Smallest AI")

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Overview

Smallest AI TTS API Reference

Example Implementation

Installation

Prerequisites

Configuration

Settings

Usage

Basic Setup

With Voice Customization

Using Lightning V2 Model

Updating Settings at Runtime

Notes

Event Handlers

​Overview

Smallest AI TTS API Reference

Example Implementation

​Installation

​Prerequisites

​Configuration

​Settings

​Usage

​Basic Setup

​With Voice Customization

​Using Lightning V2 Model

​Updating Settings at Runtime

​Notes

​Event Handlers

Overview

Installation

Prerequisites

Configuration

Settings

Usage

Basic Setup

With Voice Customization

Using Lightning V2 Model

Updating Settings at Runtime

Notes

Event Handlers