HeyGen Text-to-Speech

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

uv add pipecat-ai

HeyGen TTS needs no extra dependencies. The 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

str

required

HeyGen API key.

str

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

HeyGen WebSocket base URL.

int | None

default:"None"

Output audio sample rate in Hz. When None, uses the pipeline’s sample rate.

bool | None

default:"None"

Whether <break time="1s" /> tags become pauses. Without it, HeyGen closes the WebSocket when the text contains a break tag.

bool | None

default:"None"

Whether HeyGen stores a copy of the audio and text. When None, HeyGen stores them.

str | None

default:"None"

Your identifier for the end user, recorded with HeyGen’s usage for attribution.

TextAggregationMode | None

default:"None"

How incoming text is aggregated before synthesis. TextAggregationMode.TOKEN streams LLM tokens as they arrive, and HeyGen generates at each sentence end.

HeyGenTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

Settings

Runtime-configurable settings passed via the settings constructor argument using HeyGenTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame; any change reconnects the WebSocket. See Service Settings for details.

Parameter	Type	Default	Description
`model`	`str`	`"heygen-voice-1-turbo"`	HeyGen Voice model: `heygen-voice-1`, `heygen-voice-1-turbo`, or `heygen-voice-1-turbo-free`. (Inherited.)
`voice`	`str`	Nadine’s public voice ID	HeyGen voice ID: a public voice or an instant clone in your workspace. (Inherited.)
`language`	`Language \| str`	`None`	Language of the text. When `None`, HeyGen detects it. (Inherited.)
`apply_text_normalization`	`"auto" \| "on" \| "off"`	`None`	Text normalization mode. When `None`, HeyGen uses `"auto"`.
`expressiveness_boost`	`float`	`None`	Voice expressiveness from 0.0 to 1.0. When `None`, HeyGen chooses it.

HeyGenHttpTTSService

str

required

HeyGen API key.

aiohttp.ClientSession

required

Shared aiohttp session for HTTP requests.

str

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

HeyGen API base URL.

int | None

default:"None"

Output audio sample rate in Hz. When None, uses the pipeline’s sample rate.

HeyGenHttpTTSService.Settings

default:"None"

Runtime-configurable settings. See HTTP Settings below.

HTTP Settings

Passed via HeyGenHttpTTSService.Settings(...) and updatable with TTSUpdateSettingsFrame.

Parameter	Type	Default	Description
`model`	`str`	`"heygen-voice-1-turbo"`	HeyGen Voice model: `heygen-voice-1`, `heygen-voice-1-turbo`, or `heygen-voice-1-turbo-free`. (Inherited.)
`voice`	`str`	Nadine’s public voice ID	HeyGen voice ID: a public voice, or an instant or professional clone. A professional clone needs `heygen-voice-1`. (Inherited.)
`language`	`Language \| str`	`None`	Language of the text. When `None`, HeyGen detects it. (Inherited.)

Usage

Basic Setup

import os

from pipecat.services.heygen.tts import HeyGenTTSService

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

Professional Voice Clones

Only HeyGenHttpTTSService serves professional voice clones, and they need the heygen-voice-1 model:

import os

import aiohttp

from pipecat.services.heygen.tts import HeyGenHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = HeyGenHttpTTSService(
        api_key=os.getenv("HEYGEN_API_KEY"),
        aiohttp_session=session,
        settings=HeyGenHttpTTSService.Settings(
            model="heygen-voice-1",
            voice="your-professional-clone-id",
        ),
    )

Notes

Chinese and Japanese: Set language on HeyGenTTSService to 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-free runs on shared capacity with no availability guarantee. When capacity is full, HeyGen refuses the turn and the service pushes an ErrorFrame. To keep the bot speaking, put a paid model behind it in a ServiceSwitcher with ServiceSwitcherStrategyFailover.

Event Handlers

HeyGenTTSService supports the standard service connection events:

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

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

Get Started

Standards

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

HeyGen Text-to-Speech

Overview

HeyGen TTS API Reference

Example Implementation

HTTP Example

HeyGen Documentation

Installation

Prerequisites

HeyGen Account Setup

Required Environment Variables

Configuration

HeyGenTTSService

Settings

HeyGenHttpTTSService

HTTP Settings

Usage

Basic Setup

Professional Voice Clones

Notes

Event Handlers

​Overview

HeyGen TTS API Reference

Example Implementation

HTTP Example

HeyGen Documentation

​Installation

​Prerequisites

​HeyGen Account Setup

​Required Environment Variables

​Configuration

​HeyGenTTSService

​Settings

​HeyGenHttpTTSService

​HTTP Settings

​Usage

​Basic Setup

​Professional Voice Clones

​Notes

​Event Handlers

Overview

Installation

Prerequisites

HeyGen Account Setup

Required Environment Variables

Configuration

HeyGenTTSService

Settings

HeyGenHttpTTSService

HTTP Settings

Usage

Basic Setup

Professional Voice Clones

Notes

Event Handlers