Live API

Live API обеспечивает двунаправленное голосовое и видео взаимодействие с Gemini с малой задержкой. Используя Live API, вы можете предоставить конечным пользователям возможность естественного, человеческого голосового общения, а также возможность прерывать ответы модели с помощью голосовых команд. Модель может обрабатывать ввод текста, аудио и видео, а также обеспечивать вывод текста и звука.

Вы можете попробовать Live API в Google AI Studio .

Что нового

Ознакомьтесь с журналом изменений , чтобы узнать о последних новых функциях и возможностях Live API!

Используйте Live API

В этом разделе описывается, как использовать Live API с одним из наших SDK. Дополнительные сведения о базовом API WebSockets см. в справочнике по API WebSockets .

Чтобы использовать все функции, обязательно установите последнюю версию SDK, например, pip install -U google-genai .

Отправлять и получать текст

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
            )

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Получить аудио

В следующем примере показано, как получить аудиоданные и записать их в .wav файл.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Un-comment this code to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())

Аудио форматы

Live API поддерживает следующие аудиоформаты:

  • Формат входного аудио: необработанный 16-битный звук PCM с частотой 16 кГц с прямым порядком байтов.
  • Выходной аудиоформат: необработанный 16-битный звук PCM с частотой 24 кГц с прямым порядком байтов.

Потоковое аудио и видео

Системные инструкции

Системные инструкции позволяют вам управлять поведением модели в зависимости от ваших конкретных потребностей и вариантов использования. Системные инструкции могут быть установлены в конфигурации установки и будут действовать в течение всего сеанса.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

Дополнительные обновления контента

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

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)
{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

Для более длинных контекстов рекомендуется предоставить сводку одного сообщения, чтобы освободить окно контекста для последующих взаимодействий.

Изменение голоса

Live API поддерживает следующие голоса: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus и Zephyr.

Чтобы указать голос, задайте имя голоса в объекте speechConfig как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)
{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Изменить язык

Live API поддерживает несколько языков .

Чтобы изменить язык, установите код языка в объекте speechConfig как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

Используйте инструменты

С помощью Live API вы можете определить такие инструменты, как вызов функций , выполнение кода и поиск Google .

Используйте вызов функции

Вы можете определить объявления функций как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по вызову функций .

После получения вызовов инструментов клиент должен ответить списком объектов FunctionResponse , используя метод session.send_tool_response .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


if __name__ == "__main__":
    asyncio.run(main())

Из одного приглашения модель может генерировать несколько вызовов функций и код, необходимый для объединения их выходных данных в цепочку. Этот код выполняется в изолированной среде, генерируя последующие сообщения BidiGenerateContentToolCall . Выполнение приостанавливается до тех пор, пока не станут доступны результаты каждого вызова функции, что обеспечивает последовательную обработку.

Аудиовходы и аудиовыходы отрицательно влияют на способность модели использовать вызов функций.

Использовать выполнение кода

Вы можете определить выполнение кода как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по выполнению кода .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Вы можете включить заземление с помощью поиска Google как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по заземлению .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Комбинируйте несколько инструментов

Вы можете комбинировать несколько инструментов в Live API:

prompt = """
Hey, I need you to do three things for me.

1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"code_execution": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

config = {"response_modalities": ["TEXT"], "tools": tools}

Обработка прерываний

Пользователи могут прервать вывод модели в любой момент. Когда обнаружение голосовой активности (VAD) обнаруживает прерывание, текущая генерация отменяется и отменяется. В истории сеанса сохраняется только информация, уже отправленная клиенту. Затем сервер отправляет сообщение BidiGenerateContentServerContent , чтобы сообщить о прерывании.

Кроме того, сервер Gemini отбрасывает все ожидающие вызовы функций и отправляет сообщение BidiGenerateContentServerContent с идентификаторами отмененных вызовов.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

Настройка обнаружения голосовой активности (VAD)

Вы можете настроить или отключить обнаружение голосовой активности (VAD).

Использовать автоматический VAD

По умолчанию модель автоматически выполняет VAD для непрерывного входного аудиопотока. VAD можно настроить с помощью поля realtimeInputConfig.automaticActivityDetection конфигурации установки .

Когда аудиопоток приостанавливается более чем на секунду (например, из-за того, что пользователь выключил микрофон), должно быть отправлено событие audioStreamEnd для очистки любого кэшированного звука. Клиент может возобновить отправку аудиоданных в любое время.

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

При использовании send_realtime_input API будет автоматически реагировать на звук на основе VAD. В то время как send_client_content добавляет сообщения в контекст модели по порядку, send_realtime_input оптимизирован для оперативности за счет детерминированного порядка.

Настройка автоматического VAD

Для большего контроля над активностью VAD вы можете настроить следующие параметры. Дополнительную информацию см. в справочнике по API .

from google.genai import types

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

Отключить автоматический VAD

Альтернативно, автоматический VAD можно отключить, установив для realtimeInputConfig.automaticActivityDetection.disabled значение true в сообщении настройки. В этой конфигурации клиент отвечает за обнаружение речи пользователя и отправку сообщений activityStart и activityEnd в подходящее время. audioStreamEnd не отправляется в этой конфигурации. Вместо этого любое прерывание потока отмечается сообщением activityEnd .

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

Получить количество токенов

Общее количество использованных токенов можно найти в поле useMetadata возвращаемого сообщения сервера.

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

Продлить продолжительность сеанса

Максимальная продолжительность сеанса может быть увеличена до неограниченной с помощью двух механизмов:

Кроме того, до завершения сеанса вы получите сообщение GoAway , что позволит вам предпринять дальнейшие действия.

Включить сжатие контекстного окна

Чтобы включить более длительные сеансы и избежать внезапного прекращения соединения, вы можете включить сжатие контекстного окна, установив поле contextWindowCompression как часть конфигурации сеанса.

В ContextWindowCompressionConfig вы можете настроить механизм скользящего окна и количество токенов , запускающих сжатие.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Настроить возобновление сеанса

Чтобы предотвратить завершение сеанса, когда сервер периодически сбрасывает соединение WebSocket, настройте поле sessionResumption в конфигурации установки .

Передача этой конфигурации заставляет сервер отправлять сообщения SessionResumptionUpdate , которые можно использовать для возобновления сеанса путем передачи последнего токена возобновления в качестве SessionResumptionConfig.handle последующего соединения.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        config=types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

if __name__ == "__main__":
    asyncio.run(main())

Получите сообщение до разрыва сеанса

Сервер отправляет сообщение GoAway , которое сигнализирует о том, что текущее соединение скоро будет разорвано. Это сообщение включает в себя timeLeft , указывающее оставшееся время и позволяющее вам предпринять дальнейшие действия, прежде чем соединение будет прервано как ABORTED.

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

Получите сообщение, когда генерация будет завершена

Сервер отправляет сообщение GenerationComplete , которое сигнализирует о том, что модель завершила генерацию ответа.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

Изменить разрешение мультимедиа

Вы можете указать разрешение мультимедиа для входного мультимедиа, задав поле mediaResolution как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Получайте аудиотранскрипции

Вы можете включить транскрипцию аудиовыхода модели. Язык транскрипции выводится из ответа модели.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"],
          "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)


if __name__ == "__main__":
    asyncio.run(main())

Ограничения

При планировании проекта учитывайте следующие ограничения Live API и Gemini 2.0.

Способы реагирования

Вы можете установить только одну модальность ответа ( TEXT или AUDIO ) для каждого сеанса в конфигурации сеанса. Попытка установить оба параметра приведет к появлению сообщения об ошибке конфигурации. Это означает, что вы можете настроить модель для ответа либо текстом, либо звуком, но не тем и другим в одном сеансе.

Аутентификация клиента

Live API обеспечивает только аутентификацию между серверами и не рекомендуется для прямого использования клиентом. Ввод клиента должен направляться через промежуточный сервер приложений для безопасной аутентификации с помощью Live API.

Продолжительность сеанса

Продолжительность сеанса можно увеличить до неограниченного значения, включив сжатие сеанса. Без сжатия сеансы только с аудио ограничены 15 минутами, а сеансы с аудио и видео — 2 минутами. Превышение этих ограничений без сжатия приведет к разрыву соединения.

Кроме того, вы можете настроить возобновление сеанса , чтобы клиент мог возобновить прерванный сеанс.

Контекстное окно

Сеанс имеет ограничение контекстного окна в 32 тыс. токенов.

Поддерживаемые языки

Live API поддерживает следующие языки:

Язык Код BCP-47
Немецкий (Германия) де-DE
английский (Австралия) ru-AU
Английский (Великобритания) ru-GB
английский (Индия) ru-IN
английский (США) ru-US
Испанский (США) es-США
Французский (Франция) пт-пятница
Хинди (Индия) привет-IN
Португальский (Бразилия) пт-БР
Арабский (общий) ар-ХА
Испанский (Испания) эс-ES
Французский (Канада) фр-Калифорния
Индонезийский (Индонезия) я сделал
Итальянский (Италия) это-ИТ
Японский (Япония) ja-JP
Турецкий (Турция) тр-ТР
Вьетнамский (Вьетнам) ви-ВН
Бенгальский (Индия) бн-ИН
Гуджарати (Индия) гу-ИН
Каннада (Индия) кн-ИН
Малаялам (Индия) мл-ИН
Маратхи (Индия) г-н-ИН
Тамильский (Индия) та-ИН
Телугу (Индия) те-ИН
Голландский (Нидерланды) нл-нл
Корейский (Южная Корея) ко-КР
Мандаринский китайский (Китай) cmn-CN
Польский (Польша) пл-ПЛ
Русский (Россия) ру-RU
Тайский (Таиланд) эт-Т

Сторонние интеграции

Для развертывания веб-приложений и мобильных приложений вы можете изучить варианты:

,

Live API обеспечивает двунаправленное голосовое и видео взаимодействие с Gemini с малой задержкой. Используя Live API, вы можете предоставить конечным пользователям возможность естественного, человеческого голосового общения, а также возможность прерывать ответы модели с помощью голосовых команд. Модель может обрабатывать ввод текста, аудио и видео, а также обеспечивать вывод текста и звука.

Вы можете попробовать Live API в Google AI Studio .

Что нового

Ознакомьтесь с журналом изменений , чтобы узнать о последних новых функциях и возможностях Live API!

Используйте Live API

В этом разделе описывается, как использовать Live API с одним из наших SDK. Дополнительные сведения о базовом API WebSockets см. в справочнике по API WebSockets .

Чтобы использовать все функции, обязательно установите последнюю версию SDK, например, pip install -U google-genai .

Отправлять и получать текст

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
            )

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Получить аудио

В следующем примере показано, как получить аудиоданные и записать их в .wav файл.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Un-comment this code to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())

Аудио форматы

Live API поддерживает следующие аудиоформаты:

  • Формат входного аудио: необработанный 16-битный звук PCM с частотой 16 кГц с прямым порядком байтов.
  • Выходной аудиоформат: необработанный 16-битный звук PCM с частотой 24 кГц с прямым порядком байтов.

Потоковое аудио и видео

Системные инструкции

Системные инструкции позволяют вам управлять поведением модели в зависимости от ваших конкретных потребностей и вариантов использования. Системные инструкции могут быть установлены в конфигурации установки и будут действовать в течение всего сеанса.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

Дополнительные обновления контента

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

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)
{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

Для более длинных контекстов рекомендуется предоставить сводку одного сообщения, чтобы освободить окно контекста для последующих взаимодействий.

Изменение голоса

Live API поддерживает следующие голоса: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus и Zephyr.

Чтобы указать голос, задайте имя голоса в объекте speechConfig как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)
{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Изменить язык

Live API поддерживает несколько языков .

Чтобы изменить язык, установите код языка в объекте speechConfig как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

Используйте инструменты

С помощью Live API вы можете определить такие инструменты, как вызов функций , выполнение кода и поиск Google .

Используйте вызов функции

Вы можете определить объявления функций как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по вызову функций .

После получения вызовов инструментов клиент должен ответить списком объектов FunctionResponse , используя метод session.send_tool_response .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


if __name__ == "__main__":
    asyncio.run(main())

Из одного приглашения модель может генерировать несколько вызовов функций и код, необходимый для объединения их выходных данных в цепочку. Этот код выполняется в изолированной среде, генерируя последующие сообщения BidiGenerateContentToolCall . Выполнение приостанавливается до тех пор, пока не станут доступны результаты каждого вызова функции, что обеспечивает последовательную обработку.

Аудиовходы и аудиовыходы отрицательно влияют на способность модели использовать вызов функций.

Использовать выполнение кода

Вы можете определить выполнение кода как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по выполнению кода .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Вы можете включить заземление с помощью поиска Google как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по заземлению .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Комбинируйте несколько инструментов

Вы можете комбинировать несколько инструментов в Live API:

prompt = """
Hey, I need you to do three things for me.

1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"code_execution": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

config = {"response_modalities": ["TEXT"], "tools": tools}

Обработка прерываний

Пользователи могут прервать вывод модели в любой момент. Когда обнаружение голосовой активности (VAD) обнаруживает прерывание, текущая генерация отменяется и отменяется. В истории сеанса сохраняется только информация, уже отправленная клиенту. Затем сервер отправляет сообщение BidiGenerateContentServerContent , чтобы сообщить о прерывании.

Кроме того, сервер Gemini отбрасывает все ожидающие вызовы функций и отправляет сообщение BidiGenerateContentServerContent с идентификаторами отмененных вызовов.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

Настройка обнаружения голосовой активности (VAD)

Вы можете настроить или отключить обнаружение голосовой активности (VAD).

Использовать автоматический VAD

По умолчанию модель автоматически выполняет VAD для непрерывного входного аудиопотока. VAD можно настроить с помощью поля realtimeInputConfig.automaticActivityDetection конфигурации установки .

Когда аудиопоток приостанавливается более чем на секунду (например, из-за того, что пользователь выключил микрофон), должно быть отправлено событие audioStreamEnd для очистки любого кэшированного звука. Клиент может возобновить отправку аудиоданных в любое время.

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

При использовании send_realtime_input API будет автоматически реагировать на звук на основе VAD. В то время как send_client_content добавляет сообщения в контекст модели по порядку, send_realtime_input оптимизирован для оперативности за счет детерминированного порядка.

Настройка автоматического VAD

Для большего контроля над активностью VAD вы можете настроить следующие параметры. Дополнительную информацию см. в справочнике по API .

from google.genai import types

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

Отключить автоматический VAD

Альтернативно, автоматический VAD можно отключить, установив для realtimeInputConfig.automaticActivityDetection.disabled значение true в сообщении настройки. В этой конфигурации клиент отвечает за обнаружение речи пользователя и отправку сообщений activityStart и activityEnd в подходящее время. audioStreamEnd не отправляется в этой конфигурации. Вместо этого любое прерывание потока отмечается сообщением activityEnd .

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

Получить количество токенов

Общее количество использованных токенов можно найти в поле useMetadata возвращаемого сообщения сервера.

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

Продлить продолжительность сеанса

Максимальная продолжительность сеанса может быть увеличена до неограниченной с помощью двух механизмов:

Кроме того, до завершения сеанса вы получите сообщение GoAway , что позволит вам предпринять дальнейшие действия.

Включить сжатие контекстного окна

Чтобы включить более длительные сеансы и избежать внезапного прекращения соединения, вы можете включить сжатие контекстного окна, установив поле contextWindowCompression как часть конфигурации сеанса.

В ContextWindowCompressionConfig вы можете настроить механизм скользящего окна и количество токенов , запускающих сжатие.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Настроить возобновление сеанса

Чтобы предотвратить завершение сеанса, когда сервер периодически сбрасывает соединение WebSocket, настройте поле sessionResumption в конфигурации установки .

Передача этой конфигурации заставляет сервер отправлять сообщения SessionResumptionUpdate , которые можно использовать для возобновления сеанса путем передачи последнего токена возобновления в качестве SessionResumptionConfig.handle последующего соединения.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        config=types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

if __name__ == "__main__":
    asyncio.run(main())

Получите сообщение до разрыва сеанса

Сервер отправляет сообщение GoAway , которое сигнализирует о том, что текущее соединение скоро будет разорвано. Это сообщение включает в себя timeLeft , указывающее оставшееся время и позволяющее вам предпринять дальнейшие действия, прежде чем соединение будет прервано как ABORTED.

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

Получите сообщение, когда генерация будет завершена

Сервер отправляет сообщение GenerationComplete , которое сигнализирует о том, что модель завершила генерацию ответа.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

Изменить разрешение мультимедиа

Вы можете указать разрешение мультимедиа для входного мультимедиа, задав поле mediaResolution как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Получайте аудиотранскрипции

Вы можете включить транскрипцию аудиовыхода модели. Язык транскрипции выводится из ответа модели.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"],
          "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)


if __name__ == "__main__":
    asyncio.run(main())

Ограничения

При планировании проекта учитывайте следующие ограничения Live API и Gemini 2.0.

Способы реагирования

Вы можете установить только одну модальность ответа ( TEXT или AUDIO ) для каждого сеанса в конфигурации сеанса. Попытка установить оба параметра приведет к появлению сообщения об ошибке конфигурации. Это означает, что вы можете настроить модель для ответа либо текстом, либо звуком, но не тем и другим в одном сеансе.

Аутентификация клиента

Live API обеспечивает только аутентификацию между серверами и не рекомендуется для прямого использования клиентом. Ввод клиента должен направляться через промежуточный сервер приложений для безопасной аутентификации с помощью Live API.

Продолжительность сеанса

Продолжительность сеанса можно увеличить до неограниченного значения, включив сжатие сеанса. Без сжатия сеансы только с аудио ограничены 15 минутами, а сеансы с аудио и видео — 2 минутами. Превышение этих ограничений без сжатия приведет к разрыву соединения.

Кроме того, вы можете настроить возобновление сеанса , чтобы клиент мог возобновить прерванный сеанс.

Контекстное окно

Сеанс имеет ограничение контекстного окна в 32 тыс. токенов.

Поддерживаемые языки

Live API поддерживает следующие языки:

Язык Код BCP-47
Немецкий (Германия) де-DE
английский (Австралия) ru-AU
Английский (Великобритания) ru-GB
английский (Индия) ru-IN
английский (США) ru-US
Испанский (США) es-США
Французский (Франция) пт-пятница
Хинди (Индия) привет-IN
Португальский (Бразилия) пт-БР
Арабский (общий) ар-ХА
Испанский (Испания) эс-ES
Французский (Канада) фр-Калифорния
Индонезийский (Индонезия) я сделал
Итальянский (Италия) это-ИТ
Японский (Япония) ja-JP
Турецкий (Турция) тр-ТР
Вьетнамский (Вьетнам) ви-ВН
Бенгальский (Индия) бн-ИН
Гуджарати (Индия) гу-ИН
Каннада (Индия) кн-ИН
Малаялам (Индия) мл-ИН
Маратхи (Индия) г-н-ИН
Тамильский (Индия) та-ИН
Телугу (Индия) те-ИН
Голландский (Нидерланды) нл-нл
Корейский (Южная Корея) ко-КР
Мандаринский китайский (Китай) cmn-CN
Польский (Польша) пл-ПЛ
Русский (Россия) ру-RU
Тайский (Таиланд) эт-Т

Сторонние интеграции

Для развертывания веб-приложений и мобильных приложений вы можете изучить варианты:

,

Live API обеспечивает двунаправленное голосовое и видео взаимодействие с Gemini с малой задержкой. Используя Live API, вы можете предоставить конечным пользователям возможность естественного, человеческого голосового общения, а также возможность прерывать ответы модели с помощью голосовых команд. Модель может обрабатывать ввод текста, аудио и видео, а также обеспечивать вывод текста и звука.

Вы можете попробовать Live API в Google AI Studio .

Что нового

Ознакомьтесь с журналом изменений , чтобы узнать о последних новых функциях и возможностях Live API!

Используйте Live API

В этом разделе описывается, как использовать Live API с одним из наших SDK. Дополнительные сведения о базовом API WebSockets см. в справочнике по API WebSockets .

Чтобы использовать все функции, обязательно установите последнюю версию SDK, например, pip install -U google-genai .

Отправлять и получать текст

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
            )

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Получить аудио

В следующем примере показано, как получить аудиоданные и записать их в .wav файл.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Un-comment this code to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())

Аудио форматы

Live API поддерживает следующие аудиоформаты:

  • Формат входного аудио: необработанный 16-битный звук PCM с частотой 16 кГц с прямым порядком байтов.
  • Выходной аудиоформат: необработанный 16-битный звук PCM с частотой 24 кГц с прямым порядком байтов.

Потоковое аудио и видео

Системные инструкции

Системные инструкции позволяют вам управлять поведением модели в зависимости от ваших конкретных потребностей и вариантов использования. Системные инструкции могут быть установлены в конфигурации установки и будут действовать в течение всего сеанса.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

Дополнительные обновления контента

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

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)
{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

Для более длинных контекстов рекомендуется предоставить сводку одного сообщения, чтобы освободить окно контекста для последующих взаимодействий.

Изменение голоса

Live API поддерживает следующие голоса: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus и Zephyr.

Чтобы указать голос, задайте имя голоса в объекте speechConfig как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)
{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Изменить язык

Live API поддерживает несколько языков .

Чтобы изменить язык, установите код языка в объекте speechConfig как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

Используйте инструменты

С помощью Live API вы можете определить такие инструменты, как вызов функций , выполнение кода и поиск Google .

Используйте вызов функции

Вы можете определить объявления функций как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по вызову функций .

После получения вызовов инструментов клиент должен ответить списком объектов FunctionResponse , используя метод session.send_tool_response .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


if __name__ == "__main__":
    asyncio.run(main())

Из одного приглашения модель может генерировать несколько вызовов функций и код, необходимый для объединения их выходных данных в цепочку. Этот код выполняется в изолированной среде, генерируя последующие сообщения BidiGenerateContentToolCall . Выполнение приостанавливается до тех пор, пока не станут доступны результаты каждого вызова функции, что обеспечивает последовательную обработку.

Аудиовходы и аудиовыходы отрицательно влияют на способность модели использовать вызов функций.

Использовать выполнение кода

Вы можете определить выполнение кода как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по выполнению кода .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Вы можете включить заземление с помощью поиска Google как часть конфигурации сеанса. Дополнительную информацию см. в руководстве по заземлению .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Комбинируйте несколько инструментов

Вы можете комбинировать несколько инструментов в Live API:

prompt = """
Hey, I need you to do three things for me.

1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"code_execution": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

config = {"response_modalities": ["TEXT"], "tools": tools}

Обработка прерываний

Пользователи могут прервать вывод модели в любой момент. Когда обнаружение голосовой активности (VAD) обнаруживает прерывание, текущая генерация отменяется и отменяется. В истории сеанса сохраняется только информация, уже отправленная клиенту. Затем сервер отправляет сообщение BidiGenerateContentServerContent , чтобы сообщить о прерывании.

Кроме того, сервер Gemini отбрасывает все ожидающие вызовы функций и отправляет сообщение BidiGenerateContentServerContent с идентификаторами отмененных вызовов.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

Настройка обнаружения голосовой активности (VAD)

Вы можете настроить или отключить обнаружение голосовой активности (VAD).

Использовать автоматический VAD

По умолчанию модель автоматически выполняет VAD для непрерывного входного аудиопотока. VAD можно настроить с помощью поля realtimeInputConfig.automaticActivityDetection конфигурации установки .

Когда аудиопоток приостанавливается более чем на секунду (например, из-за того, что пользователь выключил микрофон), должно быть отправлено событие audioStreamEnd для очистки любого кэшированного звука. Клиент может возобновить отправку аудиоданных в любое время.

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

При использовании send_realtime_input API будет автоматически реагировать на звук на основе VAD. В то время как send_client_content добавляет сообщения в контекст модели по порядку, send_realtime_input оптимизирован для оперативности за счет детерминированного порядка.

Настройка автоматического VAD

Для большего контроля над активностью VAD вы можете настроить следующие параметры. Дополнительную информацию см. в справочнике по API .

from google.genai import types

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

Отключить автоматический VAD

Альтернативно, автоматический VAD можно отключить, установив для realtimeInputConfig.automaticActivityDetection.disabled значение true в сообщении настройки. В этой конфигурации клиент отвечает за обнаружение речи пользователя и отправку сообщений activityStart и activityEnd в подходящее время. audioStreamEnd не отправляется в этой конфигурации. Вместо этого любое прерывание потока отмечается сообщением activityEnd .

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

Получить количество токенов

Общее количество использованных токенов можно найти в поле useMetadata возвращаемого сообщения сервера.

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

Продлить продолжительность сеанса

Максимальная продолжительность сеанса может быть увеличена до неограниченной с помощью двух механизмов:

Кроме того, до завершения сеанса вы получите сообщение GoAway , что позволит вам предпринять дальнейшие действия.

Включить сжатие контекстного окна

Чтобы включить более длительные сеансы и избежать внезапного прекращения соединения, вы можете включить сжатие контекстного окна, установив поле contextWindowCompression как часть конфигурации сеанса.

В ContextWindowCompressionConfig вы можете настроить механизм скользящего окна и количество токенов , запускающих сжатие.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Настроить возобновление сеанса

Чтобы предотвратить завершение сеанса, когда сервер периодически сбрасывает соединение WebSocket, настройте поле sessionResumption в конфигурации установки .

Передача этой конфигурации заставляет сервер отправлять сообщения SessionResumptionUpdate , которые можно использовать для возобновления сеанса путем передачи последнего токена возобновления в качестве SessionResumptionConfig.handle последующего соединения.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        config=types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

if __name__ == "__main__":
    asyncio.run(main())

Получите сообщение до разрыва сеанса

Сервер отправляет сообщение GoAway , которое сигнализирует о том, что текущее соединение скоро будет разорвано. Это сообщение включает в себя timeLeft , указывающее оставшееся время и позволяющее вам предпринять дальнейшие действия, прежде чем соединение будет прервано как ABORTED.

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

Получите сообщение, когда генерация будет завершена

Сервер отправляет сообщение GenerationComplete , которое сигнализирует о том, что модель завершила генерацию ответа.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

Изменить разрешение мультимедиа

Вы можете указать разрешение мультимедиа для входного мультимедиа, задав поле mediaResolution как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Получайте аудиотранскрипции

Вы можете включить транскрипцию аудиовыхода модели. Язык транскрипции выводится из ответа модели.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"],
          "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)


if __name__ == "__main__":
    asyncio.run(main())

Ограничения

При планировании проекта учитывайте следующие ограничения Live API и Gemini 2.0.

Способы реагирования

Вы можете установить только одну модальность ответа ( TEXT или AUDIO ) для каждого сеанса в конфигурации сеанса. Попытка установить оба параметра приведет к появлению сообщения об ошибке конфигурации. Это означает, что вы можете настроить модель для ответа либо текстом, либо звуком, но не тем и другим в одном сеансе.

Аутентификация клиента

Live API обеспечивает только аутентификацию между серверами и не рекомендуется для прямого использования клиентом. Ввод клиента должен направляться через промежуточный сервер приложений для безопасной аутентификации с помощью Live API.

Продолжительность сеанса

Продолжительность сеанса можно увеличить до неограниченного значения, включив сжатие сеанса. Без сжатия сеансы только с аудио ограничены 15 минутами, а сеансы с аудио и видео — 2 минутами. Превышение этих ограничений без сжатия приведет к разрыву соединения.

Кроме того, вы можете настроить возобновление сеанса , чтобы клиент мог возобновить прерванный сеанс.

Контекстное окно

Сеанс имеет ограничение контекстного окна в 32 тыс. токенов.

Поддерживаемые языки

Live API поддерживает следующие языки:

Язык Код BCP-47
Немецкий (Германия) де-DE
английский (Австралия) ru-AU
Английский (Великобритания) ru-GB
английский (Индия) ru-IN
английский (США) ru-US
Испанский (США) es-США
Французский (Франция) пт-пятница
Хинди (Индия) привет-IN
Португальский (Бразилия) пт-БР
Арабский (общий) ар-ХА
Испанский (Испания) эс-ES
Французский (Канада) фр-Калифорния
Индонезийский (Индонезия) я сделал
Итальянский (Италия) это-ИТ
Японский (Япония) ja-JP
Турецкий (Турция) тр-ТР
Вьетнамский (Вьетнам) ви-ВН
Бенгальский (Индия) бн-ИН
Гуджарати (Индия) гу-ИН
Каннада (Индия) кн-ИН
Малаялам (Индия) мл-ИН
Маратхи (Индия) г-н-ИН
Тамильский (Индия) та-ИН
Телугу (Индия) те-ИН
Голландский (Нидерланды) нл-нл
Корейский (Южная Корея) ко-КР
Мандаринский китайский (Китай) cmn-CN
Польский (Польша) пл-ПЛ
Русский (Россия) ру-RU
Тайский (Таиланд) эт-Т

Сторонние интеграции

Для развертывания веб-приложений и мобильных приложений вы можете изучить варианты:

,

Live API обеспечивает двунаправленное голосовое и видео взаимодействие с Gemini с малой задержкой. Используя Live API, вы можете предоставить конечным пользователям возможность естественного, человеческого голосового общения, а также возможность прерывать ответы модели с помощью голосовых команд. Модель может обрабатывать ввод текста, аудио и видео, а также обеспечивать вывод текста и звука.

Вы можете попробовать Live API в Google AI Studio .

Что нового

Ознакомьтесь с журналом изменений , чтобы узнать о последних новых функциях и возможностях Live API!

Используйте Live API

В этом разделе описывается, как использовать Live API с одним из наших SDK. Дополнительные сведения о базовом API WebSockets см. в справочнике по API WebSockets .

Чтобы использовать все функции, обязательно установите последнюю версию SDK, например, pip install -U google-genai .

Отправлять и получать текст

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
            )

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Получить аудио

В следующем примере показано, как получить аудиоданные и записать их в .wav файл.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Un-comment this code to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())

Аудио форматы

Live API поддерживает следующие аудиоформаты:

  • Формат входного аудио: необработанный 16-битный звук PCM с частотой 16 кГц с прямым порядком байтов.
  • Выходной аудиоформат: RAW 16-битный PCM Audio при 24 кГц Little-Endian

Потоковой аудио и видео

Системные инструкции

Системные инструкции позволяют вам управлять поведением модели на основе ваших конкретных потребностей и вариантов использования. Системные инструкции могут быть установлены в конфигурации настройки и будут оставаться в силе в течение всего сеанса.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

Инкрементные обновления контента

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

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)
{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

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

Изменить голоса

Живой API поддерживает следующие голоса: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus и Zephyr.

Чтобы указать голос, установите голосовое имя в объекте speechConfig как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)
{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Изменение языка

Живой API поддерживает несколько языков .

Чтобы изменить язык, установите языковой код в объекте speechConfig как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

Используйте инструменты

Вы можете определить такие инструменты, как вызов функции , выполнение кода и поиск в Google с живым API.

Используйте функцию вызова

Вы можете определить объявления функций как часть конфигурации сеанса. Смотрите функцию, вызывая учебник, чтобы узнать больше.

После получения звонков инструмента клиент должен ответить списком объектов FunctionResponse , используя метод session.send_tool_response .

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


if __name__ == "__main__":
    asyncio.run(main())

Из одной приглашения модель может генерировать несколько вызовов функций и код, необходимый для цепочки их выходов. Этот код выполняется в среде песочницы, генерируя последующие сообщения BidigenerateContentToolCall . Выполнение не станет до тех пор, пока не будут доступны результаты каждого вызова функции, что обеспечивает последовательную обработку.

Аудио входы и аудиовыходы негативно влияют на способность модели использовать вызовы функций.

Используйте выполнение кода

Вы можете определить выполнение кода как часть конфигурации сеанса. Смотрите учебник по выполнению кода, чтобы узнать больше.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Вы можете включить заземление с поиском Google как часть конфигурации сеанса. Смотрите учебник по заземлению , чтобы узнать больше.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Объедините несколько инструментов

Вы можете объединить несколько инструментов в живом API:

prompt = """
Hey, I need you to do three things for me.

1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"code_execution": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

config = {"response_modalities": ["TEXT"], "tools": tools}

Обрабатывать прерывания

Пользователи могут прервать выход модели в любое время. Когда обнаружение голосовой активности (VAD) обнаруживает прерывание, продолжающееся поколение отменяется и отбрасывается. Только информация, уже отправленная клиенту, сохраняется в истории сессии. Затем сервер отправляет сообщение BidigenerateContentserverContent , чтобы сообщить о прерывании.

Кроме того, сервер Gemini отбрасывает любые ожидающие вызовы функций и отправляет сообщение BidiGenerateContentServerContent с идентификаторами отмененных вызовов.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

Настройка обнаружения голосовой активности (VAD)

Вы можете настроить или отключить обнаружение голосовой активности (VAD).

Используйте автоматический вад

По умолчанию модель автоматически выполняет VAD в непрерывном аудио входном потоке. VAD может быть настроен с помощью realtimeInputConfig.automaticActivityDetection поля конфигурации настройки .

Когда аудио -поток приостанавливается более чем на секунду (например, потому что пользователь отключил микрофон), событие audioStreamEnd следует отправлять для промывки любого кэшированного звука. Клиент может возобновить отправку аудиоданных в любое время.

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

С send_realtime_input API будет автоматически отвечать на аудио на основе VAD. В то время как send_client_content добавляет сообщения в контекст модели по порядку, send_realtime_input оптимизирован для отзывчивости за счет детерминированного упорядочения.

Настройте автоматический VAD

Для получения дополнительной контроля над активностью VAD вы можете настроить следующие параметры. См. Ссылку API для получения дополнительной информации.

from google.genai import types

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

Отключить автоматический вад

В качестве альтернативы, автоматический VAD может быть отключен, установив realtimeInputConfig.automaticActivityDetection.disabled true в сообщении настройки. В этой конфигурации клиент отвечает за обнаружение пользовательской речи и отправку сообщений activityStart и activityEnd в соответствующее время. audioStreamEnd не отправляется в эту конфигурацию. Вместо этого любое прерывание потока помечено сообщением activityEnd .

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

Получить количество токенов

Вы можете найти общее количество потребляемых токенов в поле USAGEMETADATA в возвращенном серверном сообщении.

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

Продлить продолжительность сеанса

Максимальная продолжительность сеанса может быть расширена до неограниченной с двумя механизмами:

Кроме того, вы получите послание до конца сеанса, что позволит вам предпринять дальнейшие действия.

Включить сжатие окна контекста

Чтобы включить более длительные сеансы и избежать резкого завершения подключения, вы можете включить сжатие окна контекста, установив поле ContextWindowCompression как часть конфигурации сеанса.

В ContextWindowCompressionConfig вы можете настроить механизм скользящего окна и количество токенов , которые запускают сжатие.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Настроить возобновление сеанса

Чтобы предотвратить завершение сеанса, когда сервер периодически сбрасывает подключение к WebSocket, настройте поле SessionResuraring в конфигурации настройки .

Передача этой конфигурации заставляет сервер отправлять сообщения SessionResingUpdate , которые можно использовать для возобновления сеанса путем передачи последнего токена возобновления в качестве SessionResumptionConfig.handle последующего соединения.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        config=types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

if __name__ == "__main__":
    asyncio.run(main())

Получить сообщение перед отключением сеанса

Сервер отправляет сообщение о том, что текущее соединение скоро будет прекращено. Это сообщение включает в себя Timeleft , указывающий на оставшееся время, и позволяет вам предпринять дальнейшие действия до того, как соединение будет прекращено как прерванное.

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

Получите сообщение, когда поколение завершено

Сервер отправляет сообщение GenerationComplete , которое сигнализирует о том, что модель закончила генерировать ответ.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

Измените резолюцию в СМИ

Вы можете указать разрешение носителя для входного носителя, установив поле mediaResolution как часть конфигурации сеанса:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Получить аудио транскрипции

Вы можете включить транскрипцию звукового выхода модели. Язык транскрипции выведен из ответа модели.

import asyncio
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["AUDIO"],
          "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)


if __name__ == "__main__":
    asyncio.run(main())

Ограничения

Рассмотрим следующие ограничения Live API и Gemini 2.0, когда вы планируете свой проект.

Методы ответа

Вы можете установить только одну модальность ответа ( TEXT или AUDIO ) на сеанс в конфигурации сеанса. Попытка установить оба приведет к сообщению об ошибке конфигурации. Это означает, что вы можете настроить модель для ответа с помощью текста или аудио, но не оба в одном сеансе.

Аутентификация клиента

Live API обеспечивает только сервер для аутентификации сервера и не рекомендуется для прямого использования клиента. Ввод клиента должен быть направлен через промежуточный сервер приложений для безопасной аутентификации с живым API.

Продолжительность сеанса

Продолжительность сеанса может быть продлена на неограниченное количество путем обеспечения сжатия сеанса. Без сжатия сеансы только для аудио ограничены 15 минут, а аудио плюс видео сеансы ограничены 2 минутами. Превышение этих пределов без сжатия прекратит соединение.

Кроме того, вы можете настроить возобновление сеанса , чтобы позволить клиенту возобновить сеанс, который был прекращен.

Контекст окна

Сессия имеет контекстный предел окна 32K токенов.

Поддерживаемые языки

Live API поддерживает следующие языки:

Язык Код BCP-47
Немецкий (Германия) de-de
Английский (Австралия) en-au
Английский (Великобритания) en-gb
Английский (Индия) en-in
Английский (США) en-us
Испанский (Соединенные Штаты) es-us
Французский (Франция) FR-FR
Хинди (Индия) Привет
Португальский (Бразилия) Pt-b
Арабский (общий) AR-XA
Испанский (Испания) es-es
Французский (Канада) Fr-Ca
Индонезийский (Индонезия) я сделал
Итальянский (Италия) это-это
Японский (Япония) ja-jp
Турецкий (индейка) TR-TR
Вьетнамцы (Вьетнам) Vi-Vn
Бенгальский (Индия) Bn-in
Гуджарати (Индия) Гун
Каннада (Индия) КН-В
Малаялам (Индия) Ml-in
Маратхи (Индия) MR-IN
Тамильский (Индия) та-в
Телугу (Индия) Te-in
Голландцы (Нидерланды) nl-nl
Корейский (Южная Корея) Ко-Кр
Мандарин Китайский (Китай) CMN-CN
Польский (Польша) пл
Русская (Россия) Ру-Ру
Тайский (Таиланд) th-й

Сторонние интеграции

Для развертывания веб -и мобильных приложений вы можете изучить варианты: