Neuphonic

Overview

Neuphonic provides high-quality text-to-speech synthesis with two service implementations: NeuphonicTTSService (WebSocket-based) with real-time streaming and interruption support, and NeuphonicHttpTTSService (HTTP-based) with server-sent events. NeuphonicTTSService is recommended for interactive applications requiring low latency.

Neuphonic TTS API Reference

Pipecat’s API methods for Neuphonic TTS integration

Example Implementation

Complete example with WebSocket streaming

Neuphonic Documentation

Official Neuphonic TTS API documentation

Voice Library

Browse available voices and features

Installation

To use Neuphonic services, install the required dependencies:

uv add "pipecat-ai[neuphonic]"

Prerequisites

Neuphonic Account Setup

Before using Neuphonic TTS services, you need:

Neuphonic Account: Sign up at Neuphonic
API Key: Generate an API key from your account dashboard
Voice Selection: Choose from available voice models

Required Environment Variables

NEUPHONIC_API_KEY: Your Neuphonic API key for authentication

Configuration

NeuphonicTTSService

str

required

Neuphonic API key for authentication.

str

default:"None"

deprecated

ID of the voice to use for synthesis.Deprecated in v0.0.105. Use settings=NeuphonicTTSService.Settings(...) instead.

str

default:"wss://api.neuphonic.com"

WebSocket URL for the Neuphonic API.

int

default:"22050"

Output audio sample rate in Hz.

str

default:"pcm_linear"

Audio encoding format.

TextAggregationMode

default:"TextAggregationMode.SENTENCE"

Controls how incoming text is aggregated before synthesis. SENTENCE (default) buffers text until sentence boundaries, producing more natural speech. TOKEN streams tokens directly for lower latency. Import from pipecat.services.tts_service.

bool

default:"None"

deprecated

Deprecated in v0.0.104. Use text_aggregation_mode instead.

InputParams

default:"None"

deprecated

Runtime-configurable voice and generation settings. See Settings below.Deprecated in v0.0.105. Use settings=NeuphonicTTSService.Settings(...) instead.

NeuphonicTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

NeuphonicHttpTTSService

The HTTP service uses SSE (server-sent events) for streaming audio.

str

required

Neuphonic API key for authentication.

str

default:"None"

deprecated

ID of the voice to use for synthesis.Deprecated in v0.0.105. Use settings=NeuphonicHttpTTSService.Settings(...) instead.

aiohttp.ClientSession

required

An aiohttp session for HTTP requests.

str

default:"https://api.neuphonic.com"

Base URL for the Neuphonic HTTP API.

int

default:"22050"

Output audio sample rate in Hz.

str

default:"pcm_linear"

Audio encoding format.

InputParams

default:"None"

deprecated

Runtime-configurable voice and generation settings. See Settings below.Deprecated in v0.0.105. Use settings=NeuphonicHttpTTSService.Settings(...) instead.

NeuphonicHttpTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

Settings

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

Parameter	Type	Default	Description
`model`	`str`	`None`	Model identifier. (Inherited.)
`voice`	`str`	`None`	Voice identifier. (Inherited.)
`language`	`Language \| str`	`None`	Language for synthesis. (Inherited.)
`speed`	`float`	`NOT_GIVEN`	Speech rate control.

Usage

Basic Setup (WebSocket)

from pipecat.services.neuphonic import NeuphonicTTSService

tts = NeuphonicTTSService(
    api_key=os.getenv("NEUPHONIC_API_KEY"),
    settings=NeuphonicTTSService.Settings(
        voice="your-voice-id",
    ),
)

With Customization (WebSocket)

from pipecat.services.neuphonic import NeuphonicTTSService
from pipecat.transcriptions.language import Language

tts = NeuphonicTTSService(
    api_key=os.getenv("NEUPHONIC_API_KEY"),
    sample_rate=22050,
    settings=NeuphonicTTSService.Settings(
        voice="your-voice-id",
        language=Language.FR,
        speed=1.2,
    ),
)

HTTP Service

import aiohttp
from pipecat.services.neuphonic import NeuphonicHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = NeuphonicHttpTTSService(
        api_key=os.getenv("NEUPHONIC_API_KEY"),
        settings=NeuphonicHttpTTSService.Settings(
            voice="your-voice-id",
        ),
        aiohttp_session=session,
    )

The InputParams / params= pattern is deprecated as of v0.0.105. Use Settings / settings= instead. See the Service Settings guide for migration details.

Notes

WebSocket vs HTTP: The WebSocket service (NeuphonicTTSService) supports interruption handling and keepalive connections, making it better for interactive conversations. The HTTP service (NeuphonicHttpTTSService) uses server-sent events and is simpler to integrate.
Keepalive: The WebSocket service automatically sends keepalive messages every 10 seconds to maintain the connection.
Default sample rate: Both services default to 22050 Hz, which differs from most other TTS services.

Event Handlers

Neuphonic WebSocket TTS supports the standard service connection events:

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

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

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Overview

Neuphonic TTS API Reference

Example Implementation

Neuphonic Documentation

Voice Library

Installation

Prerequisites

Neuphonic Account Setup

Required Environment Variables

Configuration

NeuphonicTTSService

NeuphonicHttpTTSService

Settings

Usage

Basic Setup (WebSocket)

With Customization (WebSocket)

HTTP Service

Notes

Event Handlers

​Overview

Neuphonic TTS API Reference

Example Implementation

Neuphonic Documentation

Voice Library

​Installation

​Prerequisites

​Neuphonic Account Setup

​Required Environment Variables

​Configuration

​NeuphonicTTSService

​NeuphonicHttpTTSService

​Settings

​Usage

​Basic Setup (WebSocket)

​With Customization (WebSocket)

​HTTP Service

​Notes

​Event Handlers

Overview

Installation

Prerequisites

Neuphonic Account Setup

Required Environment Variables

Configuration

NeuphonicTTSService

NeuphonicHttpTTSService

Settings

Usage

Basic Setup (WebSocket)

With Customization (WebSocket)

HTTP Service

Notes

Event Handlers