Live API

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

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

Что нового

У Live API появились новые функции и возможности!

Новые возможности:

• Два новых голоса и 30 новых языков с настраиваемым языком вывода.
• Настраиваемое разрешение изображения 66/256 токенов
• Настраиваемый охват поворота: отправляйте все входные данные постоянно или только тогда, когда пользователь говорит.
• Настройте, должен ли ввод прерывать модель или нет
• Настраиваемое обнаружение голосовой активности и новые события клиента для сигнализации конца поворота
• Количество токенов
• Клиентское событие для сигнализации об окончании потока.
• Потоковая передача текста
• Настраиваемое возобновление сеанса, данные сеанса хранятся на сервере в течение 24 часов.
• Поддержка более длительных сеансов с помощью скользящего контекстного окна.

Новые клиентские события:

• Конец аудиопотока/микрофон закрыт
• События начала/конца активности для ручного управления переходом поворота

Новые события на сервере:

• Уведомление об уходе, сигнализирующее о необходимости перезапустить сеанс
• Генерация завершена

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

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

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

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", http_options={'api_version': 'v1alpha'})
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. Дополнительную информацию о вызове функций см. в руководстве по вызову функций.

Инструменты должны быть определены как часть конфигурации сеанса:

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send_client_content(
        turns={
            "role": "user",
            "parts": [{"text": "Turn the lights down to a romantic level"}],
        },
        turn_complete=True,
    )

    async for response in session.receive():
        print(response.tool_call)

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

Клиент должен ответить BidiGenerateContentToolResponse .

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

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

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

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

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

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

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

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

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

Поддержка этой функции в SDK будет доступна в ближайшие недели.

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

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

from google.genai import types

async with client.aio.live.connect(
    model='gemini-2.0-flash-live-001',
    config=types.LiveConnectConfig(
        response_modalities=['AUDIO'],
    ),
) as session:
    # Session connected
    while True:
        await session.send_client_content(
            turns=types.Content(role='user', parts=[types.Part(text='Hello world!')])
        )
        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}')

            # 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

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

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

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

from google.genai import types

print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
    model="gemini-2.0-flash-live-001",
    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:
    # Session connected
    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

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

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

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

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

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

Чтобы включить более длительные сеансы и избежать внезапного прекращения соединения, вы можете включить сжатие контекстного окна, установив поле 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(),
        )
    ),
)

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

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

from google.genai import types

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

Ограничения

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

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

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

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

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

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

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

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

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

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

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

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

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

• Ежедневно
• Живой комплект