Live API

Interfejs Live API umożliwia dwukierunkowe interakcje z użyciem głosu i wideo z niewielkimi opóźnieniami dzięki Gemini. Za pomocą interfejsu API na żywo 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 Live API możesz wypróbować w Google AI Studio.

Nowości

Interfejs Live API zyskał nowe funkcje i możliwości.

Nowe możliwości:

• 2 nowe głosy i 30 nowych języków z możliwością wyboru języka wyjściowego
• Konfigurowalne rozdzielczości obrazów: 66/256 tokenów
• Możliwość konfiguracji zakresu przechwytywania: wysyłaj wszystkie dane wejściowe przez cały czas lub tylko wtedy, gdy użytkownik mówi.
• Konfigurowanie, czy dane wejściowe mają przerywać działanie modelu
• konfigurowalne wykrywanie aktywności głosowej i nowe zdarzenia klienta dotyczące sygnalizacji końca kolejki
• Liczba tokenów
• Zdarzenie klienta sygnalizujące koniec transmisji
• Strumieniowanie tekstu
• konfigurowalne wznawianie sesji z danymi sesji przechowywanymi na serwerze przez 24 godziny;
• Obsługa dłuższych sesji dzięki przesuwanemu oknu kontekstu

Nowe zdarzenia klienta:

• Zakończenie strumieniowego przesyłania dźwięku / mikrofon zamknięty
• zdarzenia rozpoczęcia/zakończenia aktywności do ręcznego sterowania przejściem na kolejny etap

Nowe zdarzenia serwera:

• Powiadomienie o zakończeniu sesji, które sygnalizuje potrzebę jej ponownego uruchomienia
• Generowanie zakończone

Korzystanie z interfejsu Live API

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

Wysyłanie i odbieranie SMS-ów

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

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

Formaty audio

Interfejs Live API 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 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ń:

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

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 Live API obsługuje te głosy: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus i Zephyr.

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

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 połączeń.

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

Konfigurowanie wykrywania aktywności głosowej (VAD)

Domyślnie model automatycznie wykrywa aktywność głosową (VAD) w ciągłym strumieniu danych wejściowych audio. Funkcję VAD można skonfigurować za pomocą pola realtimeInputConfig.automaticActivityDetection w konfiguracji konfiguracji.

Gdy strumień audio jest wstrzymany przez ponad sekundę (np. dlatego, że użytkownik wyłączył mikrofon), należy wysłać zdarzenie audioStreamEnd, aby opróżnić pamięć podręczną z dźwięku. Klient może wznowić wysyłanie danych audio w dowolnym momencie.

Automatyczne wykrywanie mowy można też wyłączyć, ustawiając wartość parametru realtimeInputConfig.automaticActivityDetection.disabled na true w wiadomości konfiguracyjnej. W tej konfiguracji klient odpowiada za wykrywanie mowy użytkownika i wysyłanie wiadomości activityStart i activityEnd w odpowiednich momentach. W ramach tej konfiguracji nie jest wysyłana wiadomość audioStreamEnd. Zamiast tego każde przerwanie strumienia jest oznaczane komunikatem activityEnd.

Obsługa tej funkcji w pakiecie SDK będzie dostępna w najbliższych tygodniach.

Pobieranie liczby tokenów

Łączną liczbę wykorzystanych tokenów znajdziesz w polu usageMetadata zwracanego komunikatu serwera.

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

Konfigurowanie wznawiania sesji

Aby zapobiec zakończeniu sesji, gdy serwer okresowo resetuje połączenie WebSocket, skonfiguruj pole sessionResumption w konfiguracji konfiguracji.

Przekazanie tej konfiguracji powoduje, że serwer wysyła wiadomości SessionResumptionUpdate, których można użyć do wznowienia sesji, przekazując ostatni token wznowienia jako SessionResumptionConfig.handle kolejnego połączenia.

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

otrzymywać wiadomość przed zakończeniem sesji;

Serwer wysyła wiadomość GoAway, która sygnalizuje, że bieżące połączenie zostanie wkrótce zakończone. Wiadomość zawiera timeLeft, czyli pozostały czas, oraz umożliwia podjęcie dalszych działań, zanim połączenie zostanie zakończone jako ABORTED.

otrzymywać wiadomość, gdy generowanie zostanie zakończone;

Serwer wysyła wiadomość generationComplete, która sygnalizuje, że model zakończył generowanie odpowiedzi.

Włącz kompresję okna kontekstowego

Aby umożliwić dłuższe sesje i uniknąć nagłego zakończenia połączenia, możesz włączyć kompresję okna kontekstowego, ustawiając pole contextWindowCompression w ramach konfiguracji sesji.

W ContextWindowCompressionConfig możesz skonfigurować mechanizm okna przesuwającego oraz liczbę tokenów, które uruchamiają kompresję.

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

Zmień rozdzielczość multimediów

Rozdzielczość multimediów wejściowych możesz określić, ustawiając pole mediaResolution w ramach konfiguracji sesji:

from google.genai import types

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

Ograniczenia

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

Sposoby odpowiedzi

W ramach konfiguracji sesji możesz ustawić tylko 1 rodzaj odpowiedzi (TEXT lub AUDIO) na sesję. Próba ustawienia obu spowoduje wyświetlenie komunikatu o błędzie konfiguracji. Oznacza to, że możesz skonfigurować model tak, aby odpowiadał w postaci tekstu lub dźwięku, ale nie w obu tych formatach w ramach tej samej sesji.

Uwierzytelnianie klienta

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

Czas trwania sesji

Czas trwania sesji można wydłużyć do nieograniczonego, włączając kompresję sesji. Bez kompresji sesje z tylko dźwiękiem są ograniczone do 15 minut, a sesje z dźwiękiem i wideo do 2 minut. Przekroczenie tych limitów bez kompresji spowoduje przerwanie połączenia.

Okno kontekstu

Okno kontekstu sesji ma limit 32 tys. tokenów.

Obsługiwane języki

Interfejs Live API obsługuje te języki:

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