> ## Documentation Index
> Fetch the complete documentation index at: https://patter-06b046ce-feat-py-gemini-tts-stt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini TTS

> Google Gemini text-to-speech — streaming PCM from gemini-3.1-flash-tts-preview, with inline delivery tags that shape prosody.

# Gemini TTS

`GeminiTTS` synthesises speech with Google's [Gemini speech models](https://ai.google.dev/gemini-api/docs/speech-generation) (`gemini-3.1-flash-tts-preview`) over the Gen AI SDK's streaming `generate_content` surface. The model emits PCM L16 at 24 kHz; the adapter resamples to the pipeline rate (16 kHz by default) and the stream handler does the final 16k to 8k mu-law step for the carrier.

<Note>
  **Beta.** The adapter is validated against the Google Gen AI SDK surface; it has
  not yet been exercised against a live phone call.
</Note>

## Install

<CodeGroup>
  ```bash Python theme={null}
  pip install "getpatter[gemini]"
  ```

  ```bash TypeScript theme={null}
  npm install getpatter @google/genai
  ```
</CodeGroup>

## Authentication

```bash theme={null}
export GEMINI_API_KEY="<your-gemini-api-key>"
```

`GEMINI_API_KEY` is read automatically when `api_key` / `apiKey` is omitted, with `GOOGLE_API_KEY` as the second fallback.

## Usage

<Note>
  Use the namespaced import (`getpatter.tts.gemini`) or the flat re-export
  (`GeminiTTS`). Both auto-resolve the key from the environment.
</Note>

<CodeGroup>
  ```python Python theme={null}
  # Namespaced import (pipeline mode)
  from getpatter.tts import gemini

  tts = gemini.TTS()                                      # reads GEMINI_API_KEY, voice "Kore"
  tts = gemini.TTS(api_key="...", voice="Puck")

  # Flat alias (equivalent)
  from getpatter import GeminiTTS

  tts = GeminiTTS()
  ```

  ```typescript TypeScript theme={null}
  // Namespaced import (pipeline mode)
  import * as gemini from "getpatter/tts/gemini";

  const tts = new gemini.TTS();                           // reads GEMINI_API_KEY, voice "Kore"
  const tts2 = new gemini.TTS({ apiKey: "...", voice: "Puck" });

  // Flat alias (equivalent)
  import { GeminiTTS } from "getpatter";

  const tts3 = new GeminiTTS();
  ```
</CodeGroup>

Plug it into an agent:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from getpatter import Patter, Twilio, DeepgramSTT, GeminiTTS

  phone = Patter(carrier=Twilio(), phone_number="+15550001234")

  agent = phone.agent(
      stt=DeepgramSTT(),
      tts=GeminiTTS(voice="Kore"),                        # GEMINI_API_KEY from env
      system_prompt="You are Acme's receptionist. Keep answers to one sentence.",
  )

  asyncio.run(phone.serve(agent))
  ```

  ```typescript TypeScript theme={null}
  // npx tsx example.ts
  import { Patter, Twilio, DeepgramSTT, GeminiTTS } from "getpatter";

  const phone = new Patter({ carrier: new Twilio(), phoneNumber: "+15550001234" });

  const agent = phone.agent({
    stt: new DeepgramSTT({}),
    tts: new GeminiTTS({ voice: "Kore" }),                // GEMINI_API_KEY from env
    systemPrompt: "You are Acme's receptionist. Keep answers to one sentence.",
  });

  await phone.serve({ agent });
  ```
</CodeGroup>

## Delivery tags

Square-bracket tags inside the text are read as delivery direction rather than spoken, so the LLM can annotate its own replies:

```python theme={null}
await tts.synthesize("[warm] Of course. [short pause] Let me check that for you.")
```

Tags such as `[warm]`, `[short pause]`, and `[sigh]` shape prosody. Everything outside the brackets is spoken verbatim.

## Output rate

The adapter emits PCM16-LE mono and declares that format to the pipeline, so the sender derives the right resample ratio instead of assuming 16 kHz.

| `target_sample_rate` | Behaviour                                                                   |
| -------------------- | --------------------------------------------------------------------------- |
| `8000`               | Resampled 24k to 8k inside the adapter.                                     |
| `16000` (default)    | Resampled 24k to 16k; the handler converts to 8 kHz mu-law for the carrier. |
| `24000`              | The model's native rate, streamed through untouched.                        |

Any other value is rejected at construction.

## Warmup

`warmup()` drains one tiny synthesis so the connection and the model are hot before the first turn. It is called automatically for outbound calls when the agent has `prewarm=True` (the default), and a failure is logged rather than raised.

## Options

| Python               | TypeScript         | Default                          | Notes                                          |
| -------------------- | ------------------ | -------------------------------- | ---------------------------------------------- |
| `api_key`            | `apiKey`           | —                                | Reads `GEMINI_API_KEY`, then `GOOGLE_API_KEY`. |
| `voice`              | `voice`            | `"Kore"`                         | Prebuilt Gemini voice name.                    |
| `model`              | `model`            | `"gemini-3.1-flash-tts-preview"` | Speech model id.                               |
| `target_sample_rate` | `targetSampleRate` | `16000`                          | Output PCM rate in Hz.                         |

## Pricing

Gemini bills the speech models per token: **$1.00 per 1M text-input tokens** plus **$20.00 per 1M audio-output tokens** (roughly 25 audio tokens per second). Patter records that as **\$0.034 per 1,000 characters** synthesised. These are preview rates — see the [Gemini API pricing page](https://ai.google.dev/gemini-api/docs/pricing) for the authoritative numbers.