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

# Gemini Live

> Google Gemini Live native-audio realtime engine — alternative to OpenAI Realtime.

# Gemini Live

`GeminiLiveAdapter` bridges a bidirectional audio stream to Google's [Gemini Live](https://ai.google.dev/gemini-api/docs/live) native-audio API. It speaks the same `connect / send_audio / receive_events / close` surface as `OpenAIRealtimeAdapter`, so you can swap engines without touching the call handler.

Use it as an alternative to OpenAI Realtime when you want native-audio Gemini voices, longer context, or lower per-minute pricing.

## Install

Native-audio Gemini Live is a `v1alpha`-only API. Install the optional extra:

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

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

Set `GEMINI_API_KEY` in your environment.

## Constructor

<CodeGroup>
  ```python Python theme={null}
  from getpatter.providers.gemini_live import (
      GeminiLiveAdapter,
      GeminiLiveModel,
      GeminiLiveVoice,
      GeminiLiveSampleRate,
  )

  adapter = GeminiLiveAdapter(
      api_key="",                                              # reads from env if you wire it
      model=GeminiLiveModel.NATIVE_AUDIO_PREVIEW_09_2025,      # default
      voice=GeminiLiveVoice.PUCK,                              # Puck | Charon | Kore | Fenrir | Aoede
      instructions="You are a helpful, concise voice assistant.",
      language="en-US",
      input_sample_rate=GeminiLiveSampleRate.HZ_16000,         # PCM16 mono in
      output_sample_rate=GeminiLiveSampleRate.HZ_24000,        # PCM16 mono out
      temperature=0.8,
  )
  ```

  ```typescript TypeScript theme={null}
  import { GeminiLiveAdapter } from "getpatter";

  const adapter = new GeminiLiveAdapter(process.env.GEMINI_API_KEY!, {
    model: "gemini-2.5-flash-native-audio-preview-09-2025",
    voice: "Puck",                                             // Puck | Charon | Kore | Fenrir | Aoede
    instructions: "You are a helpful, concise voice assistant.",
    language: "en-US",
    inputSampleRate: 16000,
    outputSampleRate: 24000,
    temperature: 0.8,
  });
  ```
</CodeGroup>

## Engine usage

Pass the `GeminiLive` engine marker to `phone.agent(...)`. Patter builds the adapter
server-side at call time and transcodes the carrier's mulaw 8 kHz to and from Gemini's
PCM16 for you:

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

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

  agent = phone.agent(
      engine=GeminiLive(voice="Puck"),                 # GEMINI_API_KEY / GOOGLE_API_KEY from env
      system_prompt="You are a helpful assistant.",
      first_message="Hi! How can I help today?",
  )

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

  ```typescript TypeScript theme={null}
  import { Patter, Twilio, GeminiLive } from "getpatter";

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

  const agent = phone.agent({
    engine: new GeminiLive({ voice: "Puck" }),
    systemPrompt: "You are a helpful assistant.",
    firstMessage: "Hi! How can I help today?",
  });

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

| Marker parameter     | Type            | Default                           | Description                                                          |
| -------------------- | --------------- | --------------------------------- | -------------------------------------------------------------------- |
| `api_key`            | `str`           | `""`                              | Google AI Studio key. Reads `GEMINI_API_KEY`, then `GOOGLE_API_KEY`. |
| `model`              | `str`           | `"gemini-3.1-flash-live-preview"` | Gemini Live model ID.                                                |
| `voice`              | `str`           | `"Puck"`                          | `Puck` / `Charon` / `Kore` / `Fenrir` / `Aoede`.                     |
| `language`           | `str \| None`   | `None`                            | BCP-47 reply language.                                               |
| `temperature`        | `float \| None` | `None`                            | `None` keeps the adapter default (`0.8`).                            |
| `input_sample_rate`  | `int`           | `16000`                           | PCM16 mono rate sent to Gemini.                                      |
| `output_sample_rate` | `int`           | `24000`                           | PCM16 mono rate Gemini returns.                                      |

The TypeScript marker additionally exposes `affectiveDialog`, `proactiveAudio`, `vad`,
`thinking`, `thinkingBudget`, and `apiVersion`. The Python adapter has no constructor
argument for those, so the Python marker omits them rather than accepting a silent
no-op. The Python adapter pins `v1alpha`, which is where native-audio models are served.

## Adapter usage

`phone.agent(engine=...)` takes the `GeminiLive` **marker**, not an adapter instance —
passing `GeminiLiveAdapter(...)` raises a `TypeError`. Drive the adapter directly only
when you are wiring your own audio transport:

```python theme={null}
import asyncio
from getpatter.providers.gemini_live import GeminiLiveAdapter

adapter = GeminiLiveAdapter(api_key="...", voice="Puck")

async def main():
    await adapter.connect()
    await adapter.send_audio(pcm16_mono_16khz)          # your own audio source
    async for event_type, payload in adapter.receive_events():
        ...
    await adapter.close()

asyncio.run(main())
```

Tools work the same way as on OpenAI Realtime — pass `tools=[Tool(...)]` on `phone.agent(...)` and Patter forwards function calls to Gemini's `function_declarations` shape.

## Models

| Model                                                               | Notes                                                                               |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `"gemini-3.1-flash-live-preview"` (engine default)                  | Flash Live preview, `v1alpha` only. What `GeminiLive()` selects.                    |
| `"gemini-2.5-flash-native-audio-preview-09-2025"` (adapter default) | Native-audio preview, `v1alpha` only. What a bare `GeminiLiveAdapter(...)` selects. |
| `"gemini-live-2.5-flash-preview"`                                   | Earlier preview, shut down on 2025-12-09.                                           |
| `"gemini-2.0-flash-exp"`                                            | Experimental preview, retired Dec 2024.                                             |

The defaults change as Google promotes native audio to GA. The `GeminiLiveModel` enum tracks the currently shipped identifiers.

## Voices

`Puck`, `Charon`, `Kore`, `Fenrir`, `Aoede` — Gemini's built-in `PrebuiltVoiceConfig` set. Pass any one as `voice=`.

## When to use Gemini Live vs alternatives

| Use Gemini Live when…                                | Use [OpenAI Realtime](/python-sdk/providers/openai-realtime) when…                 | Use [Pipeline mode](/python-sdk/agents) when…                                                  |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| You want native-audio Gemini voices and 1M+ context. | You need the broadest tool-calling ecosystem and `gpt-realtime-2` reasoning tiers. | You need provider-by-provider control (e.g. `DeepgramSTT` + `AnthropicLLM` + `ElevenLabsTTS`). |

## Notes

* Barge-in is implicit: Gemini Live runs server-side VAD and interrupts on user speech. `cancel_response()` / `cancelResponse()` is a no-op for compatibility.
* The adapter itself resamples nothing — pass PCM16 mono at `input_sample_rate` Hz. On the
  `engine=GeminiLive(...)` path Patter inserts a carrier-codec shim that decodes the carrier's
  mulaw 8 kHz up to `input_sample_rate` and mulaw-encodes `output_sample_rate` PCM back down.
* Cost is not metered: the adapter does not surface Gemini's token usage, so Gemini Live calls
  report `$0` AI cost. Telephony cost is unaffected. Same gap in the TypeScript SDK.
* Gemini Live fixes the prompt and tool list at connect time. Multi-agent `handoff_to` therefore
  logs a warning and keeps the original agent instead of swapping it.
* `google-genai` (Python) and `@google/genai` (Node) are imported lazily, so default installs of `getpatter` do not pay the load cost.

## What's Next

<CardGroup cols={2}>
  <Card title="Engines" icon="bolt" href="/python-sdk/engines">All engines side by side.</Card>
  <Card title="OpenAI Realtime" icon="bolt" href="/python-sdk/providers/openai-realtime">The default engine.</Card>
  <Card title="Agents" icon="user-gear" href="/python-sdk/agents">System prompts, tools, first messages.</Card>
  <Card title="Tools" icon="screwdriver-wrench" href="/python-sdk/tools">Function calling inside a realtime session.</Card>
</CardGroup>