Multimodal Live API

Die Multimodal Live API ermöglicht bidirektionale Sprach- und Videointeraktionen mit Gemini bei niedriger Latenz. Mit der Multimodal 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 Multimodal Live API in Google AI Studio ausprobieren.

Multimodal Live API verwenden

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

SMS senden und empfangen

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

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

Audioformate

Die Multimodal 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:

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

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

Stimme ändern

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

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

Funktionsaufrufe verwenden

Sie können Tools mit der Multimodal Live API definieren. Weitere Informationen zu Funktionsaufrufen finden Sie im Leitfaden zu Funktionsaufrufen.

Tools müssen als Teil der Sitzungskonfiguration definiert werden:

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)

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.

Der Kunde sollte mit BidiGenerateContentToolResponse antworten.

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

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 not None:
        # The generation was interrupted

Beschränkungen

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

Clientauthentifizierung

Die Multimodal Live API bietet nur eine Server-zu-Server-Authentifizierung und wird für die direkte Verwendung durch Clients nicht empfohlen. Die Clienteingabe sollte für eine sichere Authentifizierung mit der Multimodal Live API über einen Zwischenanwendungsserver geleitet werden.

Unterhaltungsverlauf

Das Modell überwacht zwar die Interaktionen während einer Sitzung, der Unterhaltungsverlauf wird jedoch nicht gespeichert. Wenn eine Sitzung endet, wird der entsprechende Kontext gelöscht.

Um eine vorherige Sitzung wiederherzustellen oder dem Modell den bisherigen Kontext der Nutzerinteraktionen zur Verfügung zu stellen, sollte die Anwendung ein eigenes Unterhaltungsprotokoll führen und diese Informationen zu Beginn einer neuen Sitzung mit einer BidiGenerateContentClientContent-Nachricht senden.

Maximale Sitzungsdauer

Die Sitzungsdauer ist auf 15 Minuten für Audio oder 2 Minuten für Audio und Video beschränkt. Wenn die Sitzungsdauer das Limit überschreitet, wird die Verbindung beendet.

Das Modell ist außerdem durch die Kontextgröße begrenzt. Wenn du neben den Video- und Audiostreams große Inhaltsblöcke sendest, kann die Sitzung früher beendet werden.

Erkennung der Sprachaktivitäten (VAD)

Das Modell führt automatisch eine Sprachaktivitätserkennung (VAD) auf einem kontinuierlichen Audioeingangsstream aus. Die Spracherkennung ist immer aktiviert und ihre Parameter können nicht konfiguriert werden.

Tokenanzahl

Die Tokenanzahl wird nicht unterstützt.

Ratenlimits

Es gelten die folgenden Ratenbegrenzungen:

• 3 gleichzeitige Sitzungen pro API-Schlüssel
• 4 Millionen Tokens pro Minute

WebSockets API-Referenz

Die Multimodal Live API ist eine zustandsorientierte API, die WebSockets verwendet. In diesem Abschnitt finden Sie weitere Informationen zur WebSockets API.

Sitzungen

Eine WebSocket-Verbindung stellt eine Sitzung zwischen dem Client und dem Gemini-Server her. Nachdem ein Client eine neue Verbindung initiiert hat, kann die Sitzung Nachrichten mit dem Server austauschen, um:

• Text, Audio oder Video an den Gemini-Server senden
• Audio-, Text- oder Funktionsaufrufanfragen vom Gemini-Server empfangen.

Mit der ersten Nachricht nach der Verbindung wird die Sitzungskonfiguration festgelegt, die das Modell, die Generierungsparameter, die Systemanweisungen und die Tools enthält.

Siehe folgende Beispielkonfiguration. Die Groß- und Kleinschreibung der Namen in SDKs kann variieren. Hier finden Sie die Konfigurationsoptionen für das 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]
}

Nachrichten senden

Um Nachrichten über die WebSocket-Verbindung auszutauschen, muss der Client ein JSON-Objekt über eine offene WebSocket-Verbindung senden. Das JSON-Objekt muss genau ein Feld aus der folgenden Objektmenge enthalten:

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

Unterstützte Clientnachrichten

Die unterstützten Clientnachrichten findest du in der folgenden Tabelle:

Nachrichten empfangen

Wenn Sie Nachrichten von Gemini empfangen möchten, warten Sie auf das WebSocket-Ereignis „message“ und analysieren Sie das Ergebnis dann gemäß der Definition der unterstützten Servernachrichten.

Weitere Informationen finden Sie hier:

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)

Servernachrichten enthalten genau eines der folgenden Felder:

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

Unterstützte Servernachrichten

Die unterstützten Servernachrichten finden Sie in der folgenden Tabelle:

Nachrichten und Ereignisse

Weitere Informationen zu gängigen Typen

Weitere Informationen zu den gängigen API-Ressourcentypen Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata und Tool finden Sie unter Inhalte generieren.

Integrationen externer Anbieter

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

• Täglich
• Livekit