Skip to main content

​
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: 
pip install "pipecat-ai[neuphonic]"

​
Prerequisites

​
Neuphonic Account Setup

Before using Neuphonic TTS services, you need:
  1. Neuphonic Account: Sign up at Neuphonic
  2. API Key: Generate an API key from your account dashboard
  3. Voice Selection: Choose from available voice models

​
Required Environment Variables

  • NEUPHONIC_API_KEY: Your Neuphonic API key for authentication

​
Configuration

​
NeuphonicTTSService

​
api_key
str
required
Neuphonic API key for authentication.
​
voice_id
str
default:"None"
deprecated
ID of the voice to use for synthesis.Deprecated in v0.0.105. Use settings=NeuphonicTTSService.Settings(...) instead.
​
url
str
default:"wss://api.neuphonic.com"
WebSocket URL for the Neuphonic API.
​
sample_rate
int
default:"22050"
Output audio sample rate in Hz.
​
encoding
str
default:"pcm_linear"
Audio encoding format.
​
text_aggregation_mode
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.
​
aggregate_sentences
bool
default:"None"
deprecated
Deprecated in v0.0.104. Use text_aggregation_mode instead.
​
params
InputParams
default:"None"
deprecated
Runtime-configurable voice and generation settings. See InputParams below.Deprecated in v0.0.105. Use settings=NeuphonicTTSService.Settings(...) instead.
​
settings
NeuphonicTTSService.Settings
default:"None"
Runtime-configurable settings. See Settings below.

​
NeuphonicHttpTTSService

The HTTP service uses SSE (server-sent events) for streaming audio.
​
api_key
str
required
Neuphonic API key for authentication.
​
voice_id
str
default:"None"
deprecated
ID of the voice to use for synthesis.Deprecated in v0.0.105. Use settings=NeuphonicHttpTTSService.Settings(...) instead.
​
aiohttp_session
aiohttp.ClientSession
required
An aiohttp session for HTTP requests.
​
url
str
default:"https://api.neuphonic.com"
Base URL for the Neuphonic HTTP API.
​
sample_rate
int
default:"22050"
Output audio sample rate in Hz.
​
encoding
str
default:"pcm_linear"
Audio encoding format.
​
params
InputParams
default:"None"
deprecated
Runtime-configurable voice and generation settings. See InputParams below.Deprecated in v0.0.105. Use settings=NeuphonicHttpTTSService.Settings(...) instead.
​
settings
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.
ParameterTypeDefaultDescription
modelstrNoneModel identifier. (Inherited.)
voicestrNoneVoice identifier. (Inherited.)
languageLanguage | strNoneLanguage for synthesis. (Inherited.)
speedfloatNOT_GIVENSpeech 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:
EventDescription
on_connectedConnected to Neuphonic WebSocket
on_disconnectedDisconnected from Neuphonic WebSocket
on_connection_errorWebSocket connection error occurred
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Neuphonic")