Модуль v.2 · Урок 1

Gemini Live API: WebSocket, PCM-аудио, barge-in

30 мин

Содержание

Чему вы научитесь
Откуда брать код
Сессия живёт по WebSocket
Форматы аудио: вход и выход разные
Минимальный запуск на Python
Ephemeral-токены: не светите ключ в браузере
Транскрипция и barge-in
Следующий урок

v.2 / Урок 1 из 3

Чему вы научитесь

Понимать, как устроена realtime speech-to-speech сессия по WebSocket
Различать форматы PCM-аудио на вход и выход
Запускать диалог на официальных примерах Gemini Live
Понимать роль ephemeral-токенов для безопасности браузера
Видеть, как работает транскрипция и перебивание (barge-in)

Откуда брать код

Google публикует официальные примеры Gemini Live API в репозитории gemini-live-api-examples: Python на Gen AI SDK и vanilla JS, работа через сырой WebSocket и через ephemeral-токены, CLI на Python и Node.

Это лучший способ понять протокол на живом коде, а не по пересказу. Дальше мы разберём ключевые идеи из этих примеров.

Сессия живёт по WebSocket

Realtime-агент держит постоянное соединение по WebSocket (WSS), а не делает отдельные HTTP-запросы на каждую реплику. Звук течёт в обе стороны непрерывным потоком, что и позволяет добиться низкой задержки.

sequenceDiagram
    participant U as Клиент (браузер/CLI)
    participant G as Gemini Live (WSS)
    U->>G: setup (модель, голос, форматы)
    U->>G: аудио-чанки PCM 16 кГц
    G-->>U: аудио-ответ PCM 24 кГц
    G-->>U: транскрипт (опционально)
    U->>G: перебивание (новый звук)
    G-->>U: останавливает ответ (barge-in)

Форматы аудио: вход и выход разные

Частая ошибка новичка — перепутать частоту дискретизации. В примерах Google вход и выход заданы по-разному.

Направление	Формат
Вход (микрофон → модель)	PCM 16-bit, 16 кГц
Выход (модель → динамик)	PCM 24-bit поток, 24 кГц

Если подать звук не в том формате, агент либо не распознает речь, либо будет «крякать». В браузере звук обычно готовят через AudioWorklet.

Минимальный запуск на Python

Идея старта проста: установить SDK, создать сессию, прокинуть звук.

Минимальная live-сессия Gemini

Наведите на строку — увидите объяснение

python

Код

На простом языке

from google import genai

Импортируем Gen AI SDK

client = genai.Client()

Создаём клиент. Ключ берётся из окружения, а не из кода

model = "gemini-3.1-flash-live-preview"

Имя live-модели. Требует проверки в документации: имена realtime-моделей меняются часто

async with client.aio.live.connect(model=model) as session:

Открываем живую сессию. Соединение держится открытым всё время разговора

await session.send_realtime_input(audio=mic_chunk)

Шлём чанк звука с микрофона в формате PCM 16 кГц

async for response in session.receive():

Слушаем поток ответа от модели

if response.data:

Если в ответе пришёл звук

play(response.data)

Проигрываем приходящие аудио-чанки 24 кГц

Нажмите на строку — увидите объяснение

Ephemeral-токены: не светите ключ в браузере

Если агент работает в браузере, нельзя зашивать туда постоянный API-ключ — его украдут из исходников страницы. Решение — ephemeral-токены: короткоживущие токены, которые сервер выдаёт клиенту на одну сессию.

Браузер подключается к Gemini Live по такому токену, а основной ключ остаётся на сервере. Примеры Google показывают обе схемы: прямой WebSocket с ключом (для серверного кода) и ephemeral-токены (для браузера).

Транскрипция и barge-in

Gemini Live умеет параллельно отдавать транскрипт разговора — это полезно для логов, аналитики и записи (пригодится в модулях v.4 и v.5).

Перебивание (barge-in) работает из коробки: если человек начал говорить поверх ответа агента, модель останавливает свою реплику. Именно это делает диалог живым, а не пошаговым «вопрос — ответ — вопрос».

Следующий урок

OpenAI Realtime (GA): модели, function tools, ephemeral-токены — соберём агента на втором вендоре и увидим различия.