Multimodal Live API

Interfejs API Multimodal Live umożliwia dwukierunkowe interakcje z użyciem głosu i wideo z niewielkimi opóźnieniami dzięki Gemini. Dzięki interfejsowi API Multimodal Live możesz zapewnić użytkownikom naturalne, ludzkie konwersacje głosowe oraz możliwość przerywania odpowiedzi modelu za pomocą poleceń głosowych. Model może przetwarzać tekst, dźwięk i wideo, a także generować tekst i dźwięk.

Interfejs API Multimodal Live możesz wypróbować w Google AI Studio.

Korzystanie z interfejsu Multimodal Live API

W tej sekcji opisaliśmy, jak używać interfejsu API Multimodal Live z jednym z naszych pakietów SDK. Więcej informacji o interfejsie WebSockets API znajdziesz w dokumentacji WebSockets API.

Wysyłanie i odbieranie SMS-ów

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())

Odbieranie dźwięku

Ten przykład pokazuje, jak odbierać dane audio i zapisywać je w pliku .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())

Formaty audio

Interfejs API Multimodal Live obsługuje te formaty audio:

• Format audio wejściowego: surowy 16-bitowy PCM z częstotliwością 16 kHz w formacie little-endian
• Format wyjściowy dźwięku: surowy 16-bitowy dźwięk PCM z częstotliwością 24 kHz w formacie little-endian

strumieniowanie dźwięku i obrazu,

Instrukcje systemowe

Instrukcje systemu umożliwiają kierowanie działaniem modelu na podstawie konkretnych potrzeb i przypadków użycia. Instrukcje dotyczące systemu można ustawić w konfiguracji i będą one obowiązywać przez całą sesję.

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"],
}

Przyrostowe aktualizacje treści

Używaj przyrostowych aktualizacji, aby wysyłać dane wejściowe tekstowe, ustalać kontekst sesji lub przywracać kontekst sesji. W przypadku krótkich kontekstów możesz wysyłać interakcje krok po kroku, aby reprezentować dokładną sekwencję zdarzeń:

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
  }
}

W przypadku dłuższych kontekstów zalecamy podanie podsumowania w jednej wiadomości, aby zwolnić okno kontekstu na potrzeby kolejnych interakcji.

Zmień głosy

Interfejs API Multimodal Live obsługuje te głosy: Aoede, Charon, Fenrir, Kore i Puck.

Aby określić głos, ustaw nazwę głosu w obiekcie speechConfig w ramach konfiguracji sesji:

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"
    }
  }
}

Korzystanie z wywołania funkcji

Za pomocą interfejsu Multimodal Live API możesz definiować narzędzia. Aby dowiedzieć się więcej o wywoływaniu funkcji, zapoznaj się z samouczkiem dotyczącym wywoływania funkcji.

Narzędzia muszą być zdefiniowane w ramach konfiguracji sesji:

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)

Na podstawie jednego prompta model może wygenerować wiele wywołań funkcji i kodu niezbędnego do połączenia ich danych wyjściowych. Ten kod jest wykonywany w środowisku piaskownicy, generując kolejne wiadomości BidiGenerateContentToolCall. Wykonanie zostaje wstrzymane do czasu, aż będą dostępne wyniki każdego wywołania funkcji, co zapewnia przetwarzanie sekwencyjne.

Klient powinien odpowiedzieć, podając BidiGenerateContentToolResponse.

Wejścia i wyjścia audio negatywnie wpływają na zdolność modelu do używania funkcji wywoływania.

Zarządzanie powiadomieniami

Użytkownicy mogą w dowolnym momencie przerwać działanie modelu. Gdy wykrywanie aktywności związanej z głosem (VAD) wykryje przerwanie, trwające generowanie zostanie anulowane i odrzucone. W historii sesji są przechowywane tylko informacje już wysłane do klienta. Następnie serwer wysyła wiadomość BidiGenerateContentServerContent, aby zgłosić przerwanie.

Dodatkowo serwer Gemini odrzuca wszystkie oczekujące wywołania funkcji i wysyła wiadomość BidiGenerateContentServerContent z identyfikatorami anulowanych wywołań.

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

Ograniczenia

Podczas planowania projektu weź pod uwagę te ograniczenia interfejsu Multimodal Live API i Gemini 2.0.

Uwierzytelnianie klienta

Interfejs Multimodal Live API zapewnia uwierzytelnianie serwera z serwerem i nie jest zalecany do bezpośredniego użycia przez klienta. Dane wejściowe klienta powinny być kierowane przez pośredni serwer aplikacji, aby zapewnić bezpieczne uwierzytelnianie za pomocą interfejsu Multimodal Live API.

Historia rozmowy

Model śledzi interakcje w ramach sesji, ale historia rozmowy nie jest przechowywana. Po zakończeniu sesji odpowiedni kontekst jest usuwany.

Aby przywrócić poprzednią sesję lub przekazać modelowi historyczny kontekst interakcji z użytkownikiem, aplikacja powinna prowadzić własny dziennik rozmów i używać wiadomości BidiGenerateContentClientContent do wysyłania tych informacji na początku nowej sesji.

Maksymalny czas trwania sesji

Czas trwania sesji jest ograniczony do 15 minut w przypadku dźwięku lub do 2 minut w przypadku dźwięku i obrazu. Gdy czas trwania sesji przekroczy limit, połączenie zostanie zakończone.

Model jest też ograniczony rozmiarem kontekstu. Wysyłanie dużych fragmentów treści wraz ze strumieniami wideo i dźwięku może spowodować wcześniejsze zakończenie sesji.

wykrywanie aktywności głosowej (VAD);

Model automatycznie wykrywa aktywność głosową (VAD) w ciągłym strumieniu danych wejściowych audio. Funkcja VAD jest zawsze włączona, a jej parametry nie są konfigurowalne.

Liczba tokenów

Liczba tokenów nie jest obsługiwana.

Ograniczenia liczby żądań

Obowiązują te limity szybkości:

• 3 jednoczesne sesje na klucz interfejsu API
• 4 mln tokenów na minutę

Materiały referencyjne interfejsu WebSocket API

Interfejs API Multimodal Live to interfejs stateful API, który korzysta z WebSockets. W tej sekcji znajdziesz dodatkowe informacje o interfejsie WebSockets API.

Sesje

Połączenie WebSocket nawiązuje sesję między klientem a serwerem Gemini. Gdy klient inicjuje nowe połączenie, sesja może wymieniać się wiadomościami z serwerem, aby:

• Wysyłanie tekstu, dźwięku lub filmu na serwer Gemini.
• odbierać prośby o wykonanie funkcji, wysłane z serwera Gemini.

Początkowy komunikat po nawiązaniu połączenia określa konfigurację sesji, która obejmuje model, parametry generowania, instrukcje systemowe i narzędzia.

Poniżej znajdziesz przykładową konfigurację. Pamiętaj, że wielkość liter w nazwach pakietów SDK może się różnić. Opcje konfiguracji pakietu Python SDK możesz sprawdzić tutaj.

{
  "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]
}

Wysyłanie wiadomości

Aby wymieniać wiadomości przez połączenie WebSocket, klient musi wysłać obiekt JSON przez otwarte połączenie WebSocket. Obiekt JSON musi mieć dokładnie jedno z tych pól:

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

Obsługiwane wiadomości od klienta

W tabeli poniżej znajdziesz obsługiwane wiadomości od klienta:

Odbieranie wiadomości

Aby otrzymywać wiadomości od Gemini, nasłuchuj zdarzenia WebSocket „message”, a potem przeanalizuj wynik zgodnie z definicją obsługiwanych wiadomości serwera.

Zapoznaj się z tymi informacjami:

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)

Komunikaty serwera będą zawierać dokładnie jedno z tych pól z podanego zestawu obiektów:

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

Obsługiwane komunikaty serwera

Obsługiwane komunikaty serwera znajdziesz w tabeli poniżej:

Wiadomości i zdarzenia

Więcej informacji o najczęstszych typach

Więcej informacji o najczęściej używanych typach zasobów API Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata i Tool znajdziesz w artykule Generowanie treści.

Integracje z rozwiązaniami innych firm

W przypadku wdrożeń aplikacji internetowych i mobilnych możesz zapoznać się z opcjami dostępnymi w tych usługach:

• Codziennie
• Livekit