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.

Smallest AI TTS API Reference

Complete API reference for all parameters and methods

Example Implementation

Complete example with WebSocket streaming

Installation

pip install "pipecat-ai[smallest]"

Prerequisites

1. Smallest AI Account: Sign up at Smallest AI
2. 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://waves-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")