Overview
HeyGenTTSService streams text to HeyGen Voice over a WebSocket and plays the audio as it arrives, with word-level timestamps so an interruption commits only the words actually spoken. HeyGenHttpTTSService streams raw PCM audio from HeyGen’s HTTP endpoint, one request per sentence, and also serves professional voice clones.
HeyGen TTS API Reference
Pipecat’s API methods for HeyGen TTS integration
Example Implementation
Complete example with the WebSocket service
HTTP Example
Complete example with the HTTP service
HeyGen Documentation
Official HeyGen Voice speech documentation
Installation
heygen extra is only for the HeyGen video avatar.
Prerequisites
HeyGen Account Setup
Before using HeyGen TTS, you need:- HeyGen Account: Sign up at HeyGen
- API Key: Generate an API key from your account
- Voice Selection: Choose a public voice ID, or use an instant or professional clone from your workspace
Required Environment Variables
HEYGEN_API_KEY: Your HeyGen API key for authentication
Configuration
HeyGenTTSService
Whether
<break time="1s" /> tags become pauses. Without it, HeyGen closes
the WebSocket when the text contains a break tag.Whether HeyGen stores a copy of the audio and text. When
None, HeyGen stores
them.Your identifier for the end user, recorded with HeyGen’s usage for
attribution.
How incoming text is aggregated before synthesis.
TextAggregationMode.TOKEN
streams LLM tokens as they arrive, and HeyGen generates at each sentence end.Runtime-configurable settings. See Settings below.
Settings
Runtime-configurable settings passed via thesettings constructor argument using HeyGenTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame; any change reconnects the WebSocket. See Service Settings for details.
HeyGenHttpTTSService
Runtime-configurable settings. See HTTP Settings below.
HTTP Settings
Passed viaHeyGenHttpTTSService.Settings(...) and updatable with TTSUpdateSettingsFrame.
Usage
Basic Setup
Professional Voice Clones
OnlyHeyGenHttpTTSService serves professional voice clones, and they need the heygen-voice-1 model:
Notes
- Chinese and Japanese: Set
languageonHeyGenTTSServiceto get per-character word timing. Without it, the service has no spaces to split words on, and the turn’s text frames arrive only when its audio ends. - Turbo Free:
heygen-voice-1-turbo-freeruns on shared capacity with no availability guarantee. When capacity is full, HeyGen refuses the turn and the service pushes anErrorFrame. To keep the bot speaking, put a paid model behind it in aServiceSwitcherwithServiceSwitcherStrategyFailover.
Event Handlers
HeyGenTTSService supports the standard service connection events: