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"
ID of the voice to use for synthesis.
​
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.
​
aggregate_sentences
bool
default:"True"
Buffer text until sentence boundaries before sending to Neuphonic.
​
params
InputParams
default:"None"
Runtime-configurable voice and generation settings. See InputParams 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"
ID of the voice to use for synthesis.
​
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"
Runtime-configurable voice and generation settings. See InputParams below.

​
InputParams

Both WebSocket and HTTP services share the same InputParams structure.
ParameterTypeDefaultDescription
languageLanguageLanguage.ENLanguage for synthesis.
speedfloat1.0Speech speed multiplier.

​
Usage

​
Basic Setup (WebSocket)

from pipecat.services.neuphonic import NeuphonicTTSService

tts = NeuphonicTTSService(
    api_key=os.getenv("NEUPHONIC_API_KEY"),
    voice_id="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"),
    voice_id="your-voice-id",
    sample_rate=22050,
    params=NeuphonicTTSService.InputParams(
        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"),
        voice_id="your-voice-id",
        aiohttp_session=session,
    )

​
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")