OpenAI Text-to-Speech

Overview

OpenAITTSService provides high-quality text-to-speech synthesis using OpenAI’s TTS API with multiple voice models including traditional TTS models and advanced GPT-based models. The service outputs 24kHz PCM audio with streaming capabilities for real-time applications.

OpenAI TTS API Reference

Pipecat’s API methods for OpenAI TTS integration

Example Implementation

Complete example with voice customization

OpenAI Documentation

Official OpenAI TTS API documentation

Voice Samples

Listen to available voice options

Installation

To use OpenAI services, install the required dependencies:

uv add "pipecat-ai[openai]"

Prerequisites

OpenAI Account Setup

Before using OpenAI TTS services, you need:

OpenAI Account: Sign up at OpenAI Platform
API Key: Generate an API key from your API keys page
Voice Selection: Choose from available voice options (alloy, ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer, verse)

Required Environment Variables

OPENAI_API_KEY: Your OpenAI API key for authentication

Configuration

OpenAITTSService

str

default:"None"

OpenAI API key for authentication. If None, uses the OPENAI_API_KEY environment variable.

str

default:"None"

Custom base URL for OpenAI API. If None, uses the default OpenAI endpoint.

AsyncHTTPClient

default:"None"

Custom async HTTP client for API requests, e.g. one with a longer request timeout. Prefer openai.DefaultAsyncHttpxClient, which keeps the SDK’s connection limits and redirect handling; a bare client uses its own defaults instead. The SDK’s HTTP client family follows the installed openai version, so build any Timeout you pass it from that same family. Defaults to None, which lets the SDK build its own client.

str

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=OpenAITTSService.Settings(...) instead.

str

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=OpenAITTSService.Settings(...) instead.

int

default:"None"

Output audio sample rate in Hz. If None, uses the pipeline’s output sample rate. OpenAI TTS only produces 24kHz audio and the service doesn’t resample it, so any other rate logs a warning and the audio plays at the wrong speed.

str

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=OpenAITTSService.Settings(instructions=...) instead.

float

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=OpenAITTSService.Settings(speed=...) instead.

InputParams

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=OpenAITTSService.Settings(...) instead.

OpenAITTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

Settings

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

Parameter	Type	Default	Description
`model`	`str`	`"gpt-4o-mini-tts"`	TTS model identifier. (Inherited from base settings.)
`voice`	`str`	`"alloy"`	Voice identifier: one of the voices listed under Prerequisites. Any other value yields an `ErrorFrame` and no audio. (Inherited from base settings.)
`language`	`Language \| str`	`None`	Language used to split text into sentences; not sent to OpenAI. (Inherited from base settings.)
`instructions`	`str`	`None`	Instructions to guide voice synthesis behavior (e.g. affect, tone, pacing).
`speed`	`float`	`None`	Voice speed control (0.25 to 4.0).

Usage

Basic Setup

import os

from pipecat.services.openai.tts import OpenAITTSService

tts = OpenAITTSService(
    api_key=os.getenv("OPENAI_API_KEY"),
    settings=OpenAITTSService.Settings(
        voice="nova",
    ),
)

With Voice Customization

from pipecat.services.openai.tts import OpenAITTSService

tts = OpenAITTSService(
    api_key=os.getenv("OPENAI_API_KEY"),
    settings=OpenAITTSService.Settings(
        voice="coral",
        model="gpt-4o-mini-tts",
        instructions="Speak in a warm, friendly tone with moderate pacing.",
        speed=1.1,
    ),
)

Updating Settings at Runtime

Voice settings can be changed mid-conversation using TTSUpdateSettingsFrame:

from pipecat.frames.frames import TTSUpdateSettingsFrame
from pipecat.services.openai.tts import OpenAITTSSettings

await worker.queue_frame(
    TTSUpdateSettingsFrame(
        delta=OpenAITTSSettings(
            instructions="Now speak more formally.",
            speed=0.9,
        )
    )
)

Notes

Model selection: The gpt-4o-mini-tts model supports the instructions parameter for controlling voice affect and tone, which traditional TTS models do not support.
HTTP-based service: OpenAI TTS uses HTTP streaming, so it does not have WebSocket connection events.

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

OpenAI Text-to-Speech

Overview

OpenAI TTS API Reference

Example Implementation

OpenAI Documentation

Voice Samples

Installation

Prerequisites

OpenAI Account Setup

Required Environment Variables

Configuration

OpenAITTSService

Settings

Usage

Basic Setup

With Voice Customization

Updating Settings at Runtime

Notes

​Overview

OpenAI TTS API Reference

Example Implementation

OpenAI Documentation

Voice Samples

​Installation

​Prerequisites

​OpenAI Account Setup

​Required Environment Variables

​Configuration

​OpenAITTSService

​Settings

​Usage

​Basic Setup

​With Voice Customization

​Updating Settings at Runtime

​Notes

Overview

Installation

Prerequisites

OpenAI Account Setup

Required Environment Variables

Configuration

OpenAITTSService

Settings

Usage

Basic Setup

With Voice Customization

Updating Settings at Runtime

Notes