Bland Text-to-Speech

Overview

Bland provides two TTS service implementations:

BlandTTSService for real-time synthesis using Bland’s WebSocket API at /v2/tts/ws. Streams LLM tokens as they arrive and maintains a single connection for the whole conversation, with support for interruptions via Bland’s cancel message.
BlandHttpTTSService for complete-text synthesis using Bland’s HTTP API at /v2/tts. Takes the complete text in one request. Voice agents should prefer BlandTTSService for 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:

uv add "pipecat-ai[bland]"

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

str

required

Bland API key for authentication.

str

default:"wss://api.bland.ai/v2/tts/ws"

WebSocket URL for the Bland realtime TTS API.

int

default:"None"

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 resampled by the output transport.

TextAggregationMode

default:"TextAggregationMode.TOKEN"

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.

BlandTTSService.Settings

default:"None"

Runtime-configurable settings. See BlandTTSService Settings below.

BlandTTSService Settings

Runtime-configurable settings passed via the settings constructor argument using BlandTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
`voice`	`str`	`2f29fdbb-c55e-4add-9c7c-93437ebf379d`	Voice identifier.
`expressiveness`	`float \| None`	`None`	0.0-1.0. Higher values produce more varied intonation. `None` leaves Bland at its default.
`stability`	`float \| None`	`None`	0.0-1.0. Higher values produce more consistent delivery. `None` leaves Bland at its default.
`model`	`str`	`None`	Model identifier. (Inherited.)
`language`	`Language \| str`	`None`	Language for synthesis. (Inherited.)

The voice sets the model; expressiveness and stability are calibrated for BTTS_V3.

BlandHttpTTSService

str

required

Bland API key for authentication.

str

default:"https://api.bland.ai/v2"

Base URL for the Bland API.

int

default:"None"

Output sample rate in Hz. When None, uses the pipeline default.

aiohttp.ClientSession

default:"None"

Optional shared aiohttp session. When omitted, the service creates and owns one.

BlandHttpTTSService.Settings

default:"None"

Runtime-configurable settings. See BlandHttpTTSService Settings below.

BlandHttpTTSService Settings

Runtime-configurable settings passed via the settings constructor argument using BlandHttpTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
`voice`	`str`	`2f29fdbb-c55e-4add-9c7c-93437ebf379d`	Voice identifier.
`expressiveness`	`float \| None`	`None`	0.0-1.0. Higher values produce more varied intonation.
`stability`	`float \| None`	`None`	0.0-1.0. Higher values produce more consistent delivery.
`model`	`str`	`None`	Model identifier. (Inherited.)
`language`	`Language \| str`	`None`	Language for synthesis. (Inherited.)

Usage

WebSocket Service

from pipecat.services.bland.tts import BlandTTSService

tts = BlandTTSService(
    api_key=os.getenv("BLAND_API_KEY"),
    settings=BlandTTSService.Settings(
        voice="2f29fdbb-c55e-4add-9c7c-93437ebf379d"
    ),
)

To aggregate text into sentences before synthesis instead of streaming tokens:

from pipecat.services.tts_service import TextAggregationMode

tts = BlandTTSService(
    api_key=os.getenv("BLAND_API_KEY"),
    text_aggregation_mode=TextAggregationMode.SENTENCE,
    settings=BlandTTSService.Settings(
        voice="2f29fdbb-c55e-4add-9c7c-93437ebf379d"
    ),
)

HTTP Service

import aiohttp
from pipecat.services.bland.tts import BlandHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = BlandHttpTTSService(
        api_key=os.getenv("BLAND_API_KEY"),
        settings=BlandHttpTTSService.Settings(
            voice="2f29fdbb-c55e-4add-9c7c-93437ebf379d"
        ),
        aiohttp_session=session,
    )

Notes

Choosing a service: BlandTTSService maintains a single WebSocket connection for the whole conversation and streams LLM tokens as they arrive, making it suitable for interactive voice agents. BlandHttpTTSService processes 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 cancel message 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 resampled by the output transport.

Event Handlers

BlandTTSService supports the standard service connection events:

Event	Description
`on_connected`	Connected to Bland WebSocket
`on_disconnected`	Disconnected from Bland
`on_connection_error`	Connection error occurred

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

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Bland Text-to-Speech

Overview

Bland TTS API Reference

WebSocket Example

HTTP Example

Bland Documentation

Installation

Prerequisites

Bland Account Setup

Required Environment Variables

Configuration

BlandTTSService

BlandTTSService Settings

BlandHttpTTSService

BlandHttpTTSService Settings

Usage

WebSocket Service

HTTP Service

Notes

Event Handlers

​Overview

Bland TTS API Reference

WebSocket Example

HTTP Example

Bland Documentation

​Installation

​Prerequisites

​Bland Account Setup

​Required Environment Variables

​Configuration

​BlandTTSService

​BlandTTSService Settings

​BlandHttpTTSService

​BlandHttpTTSService Settings

​Usage

​WebSocket Service

​HTTP Service

​Notes

​Event Handlers

Overview

Installation

Prerequisites

Bland Account Setup

Required Environment Variables

Configuration

BlandTTSService

BlandTTSService Settings

BlandHttpTTSService

BlandHttpTTSService Settings

Usage

WebSocket Service

HTTP Service

Notes

Event Handlers