Overview
Bland provides two TTS service implementations:BlandTTSServicefor real-time synthesis using Bland’s WebSocket API at/v2/tts/ws. Streams LLM tokens as they arrive and keeps its connection open across turns, with support for interruptions via Bland’scancelmessage.BlandHttpTTSServicefor complete-text synthesis using Bland’s HTTP API at/v2/tts. Takes the complete text in one request. Voice agents should preferBlandTTSServicefor streaming.
Bland TTS API Reference
Pipecat’s API methods for Bland TTS integration
WebSocket Example
Complete streaming example with token-level streaming
HTTP Example
Complete HTTP example with batch synthesis
Bland Documentation
Official Bland TTS API documentation
Installation
To use Bland TTS services, install the required dependencies:Prerequisites
Bland Account Setup
Before using Bland TTS services, you need:- Bland Account: Sign up at Bland AI
- API Key: Generate an API key from your account dashboard
- Voice Selection: Choose voice IDs from available Bland voices
Required Environment Variables
BLAND_API_KEY: Your Bland API key for authentication
Configuration
BlandTTSService
Output sample rate in Hz. When
None, uses the pipeline default. A rate Bland
does not render (8000, 16000, 24000, 44100, 48000) is replaced with 48000 and
the audio is resampled to this rate.How to aggregate incoming text before sending. Defaults to
TOKEN, streaming
LLM tokens straight to Bland for the lowest latency. Pass
TextAggregationMode.SENTENCE to aggregate text into sentences before
synthesis.Runtime-configurable settings. See BlandTTSService
Settings below.
BlandTTSService Settings
Runtime-configurable settings passed via thesettings constructor argument using BlandTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.
The voice sets the model;
expressiveness and stability are calibrated for
BTTS_V3.BlandHttpTTSService
Optional shared aiohttp session. When omitted, the service creates and owns
one.
Runtime-configurable settings. See BlandHttpTTSService
Settings below.
BlandHttpTTSService Settings
Runtime-configurable settings passed via thesettings constructor argument using BlandHttpTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.
Usage
WebSocket Service
auto_formatting on, Bland rewrites 7327412065, 732-741-2065 or “seven three two seven four one two zero six five” to 7 3 2... 7 4 1... 2 0 6 5 before synthesis, and only bills the digits.
HTTP Service
Notes
- Choosing a service:
BlandTTSServicekeeps one WebSocket connection open across turns and streams LLM tokens as they arrive, making it suitable for interactive voice agents. Bland closes a session after 60 seconds without a message, and the service reconnects on the next turn.BlandHttpTTSServiceprocesses each request as a complete batch. - Token Streaming: By default (
TextAggregationMode.TOKEN), LLM tokens are sent to Bland immediately. Bland buffers them server-side and chooses its own synthesis boundaries, so no sentence tokenizer or character threshold is needed. - Interruption Handling: Interruptions send Bland’s
cancelmessage without closing the connection, so barge-in preserves the session. - Sample Rate: Bland renders 8000, 16000, 24000, 44100, and 48000 Hz directly. A pipeline running at any other rate is served at 48000 Hz, and both
BlandTTSServiceandBlandHttpTTSServiceresample the audio to the pipeline rate. - Settings updates reconnect: On
BlandTTSService, changingvoice,expressiveness,stability, orauto_formattingcloses the session and opens a new one.
Event Handlers
BlandTTSService supports the standard service connection events: