Google Text-to-Speech

​

Overview

​

Installation

uv add "pipecat-ai[google]"

​

Prerequisites

​

Google Cloud Setup

1. Google Cloud Account: Sign up at Google Cloud Console
2. Project Setup: Create a project and enable the Text-to-Speech API
3. Service Account: Create a service account with TTS permissions
4. Authentication: Set up credentials via service account key or Application Default Credentials

​

Required Environment Variables

• GOOGLE_APPLICATION_CREDENTIALS: Path to your service account key file (recommended)
• Or use Application Default Credentials for cloud deployments
• GOOGLE_API_KEY: Gemini API key, for GeminiTTSService on the Gemini API backend

​

Configuration

​

GoogleTTSService

​

GoogleTTSService Settings

​

GoogleHttpTTSService

​

GoogleHttpTTSService Settings

​

GeminiTTSService

​

GeminiTTSService Settings

​

Usage

​

Basic Setup (Streaming)

from pipecat.services.google.tts import GoogleTTSService
from pipecat.transcriptions.language import Language

tts = GoogleTTSService(
    credentials_path="/path/to/service-account.json",
    settings=GoogleTTSService.Settings(
        voice="en-US-Chirp3-HD-Charon",
        language=Language.EN_US,
    )
)

​

HTTP Service with SSML

from pipecat.services.google.tts import GoogleHttpTTSService
from pipecat.transcriptions.language import Language

tts = GoogleHttpTTSService(
    credentials_path="/path/to/service-account.json",
    settings=GoogleHttpTTSService.Settings(
        voice="en-US-Standard-A",
        language=Language.EN_US,
        rate="110%",
        pitch="+2st",
    ),
)

​

Gemini TTS with GenAI Backend (API Key)

import os

from pipecat.services.google.tts import GeminiTTSService

tts = GeminiTTSService(
    api_key=os.getenv("GOOGLE_API_KEY"),
    settings=GeminiTTSService.Settings(
        model="gemini-3.1-flash-tts-preview",
        voice="Puck",
    )
)

​

Gemini TTS with Google Cloud Backend (Style Prompt)

from pipecat.services.google.tts import GeminiTTSService
from pipecat.transcriptions.language import Language

tts = GeminiTTSService(
    credentials_path="/path/to/service-account.json",
    settings=GeminiTTSService.Settings(
        model="gemini-3.1-flash-tts-preview",
        voice="Kore",
        language=Language.EN_US,
        prompt="Say this in a friendly and helpful tone"
    )
)

​

Notes

• Streaming vs HTTP: GoogleTTSService uses the streaming API for low latency and only supports Chirp 3 HD and Journey voices. GoogleHttpTTSService supports all Google voices including Standard and WaveNet.
• Chirp/Journey voices and SSML: Chirp and Journey voices do not support SSML. The HTTP service automatically uses plain text input for these voices, so pitch, rate, volume, emphasis, gender, and google_style have no effect on them, including on the default voice. For other voices, the text is XML-escaped before it goes into the SSML, so &, <, and > in it are safe.
• Speaking rate: For Chirp and Journey voices, use speaking_rate (float, 0.25-2.0) in settings. For other voices, use rate (string) for SSML prosody control.
• Credentials: Without credentials or credentials_path, the Google Cloud services use Application Default Credentials, and the constructor raises ValueError when none are found.
• Gemini TTS sample rate: Google TTS always outputs at 24kHz. Setting a different sample rate will produce a warning and may cause audio issues.
• Gemini TTS backends: GeminiTTSService supports two backends:
  • GenAI backend (google-genai): Simpler authentication with API key. Automatically selected when api_key is provided. Does not support multi_speaker. The prompt setting is supported by Gemini 3.8 TTS models (sent as speech_metadata.style); older models ignore it with a warning.
  • Google Cloud backend: Uses service account credentials. Supports prompt for style instructions and multi_speaker for multi-voice conversations.
• Gemini TTS model names: Model names differ by backend. Cloud Text-to-Speech accepts gemini-3.1-flash-tts-preview, gemini-2.5-flash-tts, gemini-2.5-flash-lite-preview-tts, and gemini-2.5-pro-tts. The Gemini API accepts gemini-3.8-flash-tts, gemini-3.8-flash-lite-tts, gemini-3.1-flash-tts-preview, gemini-2.5-flash-preview-tts, and gemini-2.5-pro-preview-tts. The default (gemini-3.1-flash-tts-preview) works on both.
• Gemini 3.8 TTS models: Gemini 3.8 TTS models (gemini-3.8-flash-tts, gemini-3.8-flash-lite-tts) treat the input text as a verbatim transcript. Momentary vocal events use angle-bracket tags inline (e.g., <laugh>, <sigh>, <short pause>), while sustained delivery style belongs in the prompt setting. Older Gemini models use square-bracket tags (e.g., [sigh], [whispering]) in the text instead. Requires google-genai >= 2.25.0.
• Backend selection: Pass api_key to use the GenAI backend, or credentials/credentials_path for Google Cloud. Use use_genai=True to force the GenAI backend explicitly.
• Gemini multi-speaker: Use multi_speaker=True with speaker_configs to generate conversations between multiple voices (Google Cloud backend only). Markup text with speaker aliases to control which voice speaks.
• Custom voices: Custom voices created in Voice design can be used by passing their voice_... ID as the voice setting.