Live API

Die Live API ermöglicht bidirektionale Sprach- und Videointeraktionen mit Gemini bei niedriger Latenz. Mit der Live API können Sie Endnutzern natürliche, menschenähnliche Sprachunterhaltungen bieten und ihnen die Möglichkeit geben, die Antworten des Modells per Sprachbefehl zu unterbrechen. Das Modell kann Text-, Audio- und Videoeingaben verarbeiten und Text- und Audioausgaben liefern.

Sie können die Live API in Google AI Studio ausprobieren.

Das ist neu

Im Änderungslog findest du die neuesten Funktionen und Möglichkeiten der Live API.

Live API verwenden

In diesem Abschnitt wird beschrieben, wie du die Live API mit einem unserer SDKs verwendest. Weitere Informationen zur zugrunde liegenden WebSockets API finden Sie in der WebSockets API-Referenz.

Wenn Sie alle Funktionen nutzen möchten, müssen Sie die neueste SDK-Version installieren, z.B. pip install -U google-genai.

SMS senden und empfangen

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

Audio empfangen

Im folgenden Beispiel wird gezeigt, wie Audiodaten empfangen und in eine .wav-Datei geschrieben werden.

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

Audioformate

Die Live API unterstützt die folgenden Audioformate:

  • Audioformat für Eingabe: Rohes 16-Bit-PCM-Audio mit 16 kHz und Little Endian
  • Audioausgabeformat: Rohes 16-Bit-PCM-Audio mit 24 kHz, Little Endian

Audio- und Videoinhalte streamen

Systemanweisungen

Mit Systemanweisungen können Sie das Verhalten eines Modells entsprechend Ihren spezifischen Anforderungen und Anwendungsfällen steuern. Systemanweisungen können in der Einrichtungskonfiguration festgelegt werden und bleiben für die gesamte Sitzung in Kraft.

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

Inkrementelle Inhaltsaktualisierungen

Verwenden Sie inkrementelle Updates, um Texteingaben zu senden, den Sitzungskontext festzulegen oder den Sitzungskontext wiederherzustellen. Bei kurzen Kontexten können Sie Schritt-für-Schritt-Interaktionen senden, um die genaue Abfolge der Ereignisse darzustellen:

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

Bei längeren Kontexten wird empfohlen, eine einzelne Nachrichtenzusammenfassung anzugeben, um das Kontextfenster für nachfolgende Interaktionen freizugeben.

Stimme ändern

Die Live API unterstützt die folgenden Stimmen: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus und Zephyr.

Wenn Sie eine Stimme angeben möchten, legen Sie den Sprachnamen im speechConfig-Objekt als Teil der Sitzungskonfiguration fest:

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

Sprache ändern

Die Live API unterstützt mehrere Sprachen.

Wenn du die Sprache ändern möchtest, musst du den Sprachcode im speechConfig-Objekt als Teil der Sitzungskonfiguration festlegen:

from google.genai import types

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

Tools verwenden

Mit der Live API können Sie Tools wie Funktionsaufrufe, Codeausführung und Google Suche definieren.

Funktionsaufrufe verwenden

Sie können Funktionsdeklarationen als Teil der Sitzungskonfiguration definieren. Weitere Informationen finden Sie in der Anleitung zum Funktionsaufruf.

Nachdem der Client Toolaufrufe erhalten hat, sollte er mit der Methode session.send_tool_response eine Liste von FunctionResponse-Objekten zurückgeben.

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

Anhand eines einzelnen Prompts kann das Modell mehrere Funktionsaufrufe und den Code generieren, der zum Verketten der Ausgaben erforderlich ist. Dieser Code wird in einer Sandbox-Umgebung ausgeführt und generiert nachfolgende BidiGenerateContentToolCall-Nachrichten. Die Ausführung wird pausiert, bis die Ergebnisse der einzelnen Funktionsaufrufe verfügbar sind. So wird eine sequenzielle Verarbeitung sichergestellt.

Audioeingaben und ‑ausgaben beeinträchtigen die Fähigkeit des Modells, Funktionsaufrufe zu verwenden.

Codeausführung verwenden

Sie können die Codeausführung als Teil der Sitzungskonfiguration definieren. Weitere Informationen finden Sie in der Anleitung zur Codeausführung.

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

Sie können die Funktion „Grounding mit der Google Suche“ im Rahmen der Sitzungskonfiguration aktivieren. Weitere Informationen finden Sie in der Anleitung zur Erdung.

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

Mehrere Tools kombinieren

Du kannst mehrere Tools innerhalb der Live API kombinieren:

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}

Unterbrechungen verarbeiten

Nutzer können die Ausgabe des Modells jederzeit unterbrechen. Wenn die Erkennung von Sprachaktivität (VAD) eine Unterbrechung erkennt, wird die laufende Generierung abgebrochen und verworfen. Im Sitzungsverlauf werden nur die Informationen aufbewahrt, die bereits an den Client gesendet wurden. Der Server sendet dann eine BidiGenerateContentServerContent-Nachricht, um die Unterbrechung zu melden.

Außerdem verwirft der Gemini-Server alle ausstehenden Funktionsaufrufe und sendet eine BidiGenerateContentServerContent-Nachricht mit den IDs der abgebrochenen Aufrufe.

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

Erkennung der Sprachaktivitäten konfigurieren

Sie können die Sprachaktivitätserkennung (VAD) konfigurieren oder deaktivieren.

Automatische VAD verwenden

Standardmäßig führt das Modell automatisch die VAD auf einem kontinuierlichen Audioeingabestream aus. Die VAD-Funktion kann mit dem Feld realtimeInputConfig.automaticActivityDetection der Einrichtungskonfiguration konfiguriert werden.

Wenn der Audiostream länger als eine Sekunde pausiert wird (z. B. weil der Nutzer das Mikrofon ausgeschaltet hat), sollte ein audioStreamEnd-Ereignis gesendet werden, um das im Cache gespeicherte Audio zu löschen. Der Client kann das Senden von Audiodaten jederzeit fortsetzen.

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

Bei send_realtime_input reagiert die API automatisch auf Audio basierend auf der Spracherkennung. Während send_client_content dem Modellkontext Nachrichten in der richtigen Reihenfolge hinzufügt, ist send_realtime_input auf Reaktionsfähigkeit optimiert, was zu Lasten der deterministischen Sortierung geht.

Automatische VAD konfigurieren

Sie können die folgenden Parameter konfigurieren, um die VAD-Aktivität besser zu steuern. Weitere Informationen finden Sie in der API-Referenz.

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

Automatische VAD deaktivieren

Alternativ kann die automatische VAD deaktiviert werden, indem Sie in der Einrichtungsnachricht realtimeInputConfig.automaticActivityDetection.disabled auf true festlegen. Bei dieser Konfiguration ist der Client dafür verantwortlich, die Sprache des Nutzers zu erkennen und activityStart- und activityEnd-Nachrichten zum richtigen Zeitpunkt zu senden. In dieser Konfiguration wird kein audioStreamEnd gesendet. Stattdessen wird jede Unterbrechung des Streams durch eine activityEnd-Meldung gekennzeichnet.

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

Tokenanzahl abrufen

Die Gesamtzahl der verwendeten Tokens findest du im Feld usageMetadata der zurückgegebenen Servernachricht.

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

Sitzungsdauer verlängern

Die maximale Sitzungsdauer kann mit zwei Mechanismen auf unbestimmte Zeit verlängert werden:

Außerdem erhalten Sie vor dem Ende der Sitzung eine GoAway-Nachricht, mit der Sie weitere Aktionen ausführen können.

Komprimierung des Kontextfensters aktivieren

Wenn Sie längere Sitzungen ermöglichen und ein abruptes Verbindungsende vermeiden möchten, können Sie die Komprimierung des Kontextfensters aktivieren. Legen Sie dazu das Feld contextWindowCompression als Teil der Sitzungskonfiguration fest.

In ContextWindowCompressionConfig können Sie einen Schiebefenstermechanismus und die Anzahl der Tokens konfigurieren, die die Komprimierung auslösen.

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

Sitzungswiederaufnahme konfigurieren

Wenn Sie verhindern möchten, dass die Sitzung beendet wird, wenn der Server die WebSocket-Verbindung regelmäßig zurücksetzt, konfigurieren Sie das Feld sessionResumption in der Einrichtungskonfiguration.

Wenn du diese Konfiguration übergibst, sendet der Server SessionResumptionUpdate-Nachrichten, mit denen die Sitzung fortgesetzt werden kann. Dazu wird das letzte Wiederaufnahmetoken als SessionResumptionConfig.handle der nachfolgenden Verbindung übergeben.

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

Benachrichtigung erhalten, bevor die Sitzung getrennt wird

Der Server sendet eine GoAway-Nachricht, die signalisiert, dass die aktuelle Verbindung bald beendet wird. Diese Nachricht enthält den Wert timeLeft, der die verbleibende Zeit angibt. Sie können weitere Maßnahmen ergreifen, bevor die Verbindung als ABGEBROCHEN beendet wird.

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)

Benachrichtigung erhalten, wenn die Generierung abgeschlossen ist

Der Server sendet die Nachricht generationComplete, die signalisiert, dass die Antwort vom Modell generiert wurde.

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

Medienauflösung ändern

Du kannst die Medienauflösung für die Eingabemedien angeben, indem du das Feld mediaResolution als Teil der Sitzungskonfiguration festlegst:

from google.genai import types

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

Audiotranskripte erhalten

Sie können die Transkription der Audioausgabe des Modells aktivieren. Die Sprache der Transkription wird aus der Antwort des Modells abgeleitet.

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

Beschränkungen

Beachten Sie bei der Planung Ihres Projekts die folgenden Einschränkungen der Live API und Gemini 2.0.

Antwortmodalitäten

Sie können in der Sitzungskonfiguration nur eine Antwortmodalität (TEXT oder AUDIO) pro Sitzung festlegen. Wenn Sie versuchen, beides festzulegen, wird eine Konfigurationsfehlermeldung ausgegeben. Sie können das Modell also so konfigurieren, dass es entweder mit Text oder Audio antwortet, aber nicht in derselben Sitzung mit beiden.

Clientauthentifizierung

Die Live API bietet nur eine Server-zu-Server-Authentifizierung und wird für die direkte Verwendung durch Clients nicht empfohlen. Der Client-Eingabe sollte für eine sichere Authentifizierung mit der Live API ein Zwischenanwendungsserver vorangestellt werden.

Sitzungsdauer

Die Sitzungsdauer kann auf unbegrenzt verlängert werden, indem die Sitzungskomprimierung aktiviert wird. Ohne Komprimierung sind Sitzungen nur mit Audio auf 15 Minuten und Sitzungen mit Audio und Video auf 2 Minuten begrenzt. Wird dieses Limit ohne Komprimierung überschritten, wird die Verbindung beendet.

Außerdem kannst du die Sitzungswiederaufnahme konfigurieren, damit der Client eine Sitzung fortsetzen kann, die beendet wurde.

Verlaufszeitraum

Für eine Sitzung gilt ein Kontextfensterlimit von 32.000 Tokens.

Unterstützte Sprachen

Die Live API unterstützt die folgenden Sprachen:

Sprache BCP-47-Code
Deutsch (Deutschland) de-DE
Englisch (Australien) en-AU
Englisch (Großbritannien) en-GB
Englisch (Indien) en-IN
Englisch (USA) en-US
Spanisch (USA) es-US
Französisch (Frankreich) fr-FR
Hindi (Indien) hi-IN
Portugiesisch (Brasilien) pt-BR
Arabisch (generisch) ar-XA
Spanisch (Spanien) es-ES
Französisch (Kanada) fr-CA
Indonesisch (Indonesien) id-ID
Italienisch (Italien) it-IT
Japanisch (Japan) ja-JP
Türkisch (Türkei) tr-TR
Vietnamesisch (Vietnam) vi-VN
Bengalisch (Indien) bn-IN
Gujarati (Indien) gu-IN
Kannada (Indien) kn-IN
Malayalam (Indien) ml-IN
Marathi (Indien) mr-IN
Tamil (Indien) ta-IN
Telugu (Indien) te-IN
Niederländisch (Niederlande) nl-NL
Koreanisch (Südkorea) ko-KR
Chinesisch (Mandarin, China) cmn-CN
Polnisch (Polen) pl-PL
Russisch (Russland) ru-RU
Thailändisch (Thailand) th-TH

Integrationen externer Anbieter

Für die Bereitstellung von Web- und mobilen Apps stehen folgende Optionen zur Verfügung: