Multimodal Live API

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

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

Используйте мультимодальный Live API

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

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

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

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(input=message, end_of_turn=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-exp"

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(input=message, end_of_turn=True)

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

            # Comment this out 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"],
}

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

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

from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))

{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

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

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

Мультимодальный Live API поддерживает следующие голоса: Aoede, Charon, Fenrir, Kore и Puck.

Чтобы указать голос, задайте имя голоса в объекте 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"
    }
  }
}

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

Вы можете определять инструменты с помощью Multimodal 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(input="Turn the lights down to a romantic level", end_of_turn=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

Ограничения

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

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

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

История разговоров

Хотя модель отслеживает взаимодействия во время сеанса, история разговоров не сохраняется. Когда сеанс завершается, соответствующий контекст удаляется.

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

Максимальная продолжительность сеанса

Продолжительность сеанса ограничена до 15 минут для аудио или до 2 минут для аудио и видео. Когда продолжительность сеанса превышает лимит, соединение разрывается.

Модель также ограничена размером контекста. Отправка больших фрагментов контента вместе с видео- и аудиопотоками может привести к более раннему завершению сеанса.

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

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

Количество токенов

Подсчет токенов не поддерживается.

Ограничения ставок

Применяются следующие ограничения по ставкам:

• 3 одновременных сеанса на каждый ключ API
• 4 миллиона токенов в минуту

Справочник по API WebSockets

Мультимодальный Live API — это API с отслеживанием состояния, который использует WebSockets . В этом разделе вы найдете дополнительную информацию об API WebSockets.

Сессии

Соединение WebSocket устанавливает сеанс между клиентом и сервером Gemini. После того, как клиент инициирует новое соединение, сеанс может обмениваться сообщениями с сервером, чтобы:

• Отправьте текст, аудио или видео на сервер Gemini.
• Получайте запросы аудио, текста или вызовов функций с сервера Gemini.

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

См. следующий пример конфигурации. Обратите внимание, что регистр имен в SDK может различаться. Параметры конфигурации Python SDK можно найти здесь .

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },
  "systemInstruction": string,
  "tools": [object]
}

Отправлять сообщения

Для обмена сообщениями через соединение WebSocket клиент должен отправить объект JSON через открытое соединение WebSocket. Объект JSON должен содержать ровно одно из полей из следующего набора объектов:

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Поддерживаемые клиентские сообщения

См. поддерживаемые клиентские сообщения в следующей таблице:

Получать сообщения

Чтобы получать сообщения от Gemini, прослушайте событие сообщения WebSocket, а затем проанализируйте результат в соответствии с определением поддерживаемых сообщений сервера.

См. следующее:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Сообщения сервера будут иметь ровно одно из полей из следующего набора объектов:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
}

Поддерживаемые сообщения сервера

См. поддерживаемые сообщения сервера в следующей таблице:

Сообщения и события

Дополнительная информация о распространенных типах

Дополнительные сведения о часто используемых типах ресурсов API Blob , Content , FunctionCall , FunctionResponse , GenerationConfig , GroundingMetadata и Tool см. в разделе Создание контента .

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

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

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