Leitfaden zu den Live API-Funktionen

Dieser umfassende Leitfaden behandelt die Funktionen und Konfigurationen, die mit der Live API verfügbar sind. Auf der Seite Erste Schritte mit der Live API finden Sie eine Übersicht und Beispielcode für gängige Anwendungsfälle.

Hinweis

  • Mit den grundlegenden Konzepten vertraut machen:Wenn Sie das noch nicht getan haben, lesen Sie zuerst die Seite Erste Schritte mit der Live API . Hier erfahren Sie mehr über die grundlegenden Prinzipien der Live API, ihre Funktionsweise und die verschiedenen Implementierungsansätze.
  • Live API in AI Studio ausprobieren:Es kann hilfreich sein, die Live API in Google AI Studio auszuprobieren, bevor Sie mit der Entwicklung beginnen. Wenn Sie die Live API in Google AI Studio verwenden möchten, wählen Sie Stream aus.

Modellvergleich

In der folgenden Tabelle sind die wichtigsten Unterschiede zwischen den Modellen Gemini 3.1 Flash Live Preview und Gemini 2.5 Flash Live Preview zusammengefasst:

Funktion Gemini 3.1 Flash Live Preview Gemini 2.5 Flash Live Preview
Antwort wird generiert Verwendet thinkingLevel, um den Detailgrad des Denkprozesses mit Einstellungen wie minimal, low, medium und high zu steuern. Die Standardeinstellung ist minimal, um die Latenz zu minimieren. Weitere Informationen zu Denkebenen und Budgets Verwendet thinkingBudget, um die Anzahl der Tokens für den Thinking-Modus festzulegen. Die Funktion „Dynamisches Denken“ ist standardmäßig aktiviert. Setzen Sie thinkingBudget auf 0, um die Funktion zu deaktivieren. Weitere Informationen zu Denkebenen und Budgets
Antwort erhalten Ein einzelnes Serverereignis kann mehrere Inhaltsteile gleichzeitig enthalten, z. B. inlineData und ein Transkript. Achten Sie darauf, dass in Ihrem Code alle Teile jedes Ereignisses verarbeitet werden, damit keine Inhalte fehlen. Jedes Serverereignis enthält nur einen Inhaltsteil. Teile werden in separaten Ereignissen bereitgestellt.
Kundeninhalte send_client_content wird nur zum Erstellen des Verlaufs des ursprünglichen Kontexts unterstützt. Dazu muss initial_history_in_client_content in der Sitzungskonfiguration festgelegt werden. Wenn Sie während der Unterhaltung Textupdates senden möchten, verwenden Sie stattdessen send_realtime_input. send_client_content wird während der gesamten Unterhaltung unterstützt, um inkrementelle Inhaltsaktualisierungen zu senden und Kontext zu schaffen.
Abdeckung für die Navigation Die Standardeinstellung ist TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO. Der Zug des Modells umfasst erkannte Audioaktivitäten und alle Videoframes. Die Standardeinstellung ist TURN_INCLUDES_ONLY_ACTIVITY. Der Zug des Modells umfasst nur die erkannte Aktivität.
Benutzerdefinierte VAD (activity_start/activity_end) Unterstützt. Deaktivieren Sie die automatische VAD und senden Sie activityStart- und activityEnd-Nachrichten manuell, um die Sprecherwechsel zu steuern. Unterstützt. Deaktivieren Sie die automatische VAD und senden Sie activityStart- und activityEnd-Nachrichten manuell, um die Sprecherwechsel zu steuern.
Automatische VAD-Konfiguration Unterstützt. Konfigurieren Sie Parameter wie start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms und silence_duration_ms. Unterstützt. Konfigurieren Sie Parameter wie start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms und silence_duration_ms.
Asynchrone Funktionsaufrufe (behavior: NON_BLOCKING) Nicht unterstützt. Funktionsaufrufe sind nur sequenziell möglich. Das Modell beginnt erst mit der Antwort, wenn Sie die Tool-Antwort gesendet haben. Unterstützt. Legen Sie behavior für eine Funktionsdeklaration auf NON_BLOCKING fest, damit das Modell während der Ausführung der Funktion weiter interagieren kann. Mit dem Parameter scheduling (INTERRUPT, WHEN_IDLE oder SILENT) können Sie festlegen, wie das Modell Antworten verarbeitet.
Proaktive Audiofunktionen Nicht unterstützt Unterstützt. Wenn diese Option aktiviert ist, kann das Modell proaktiv entscheiden, nicht zu antworten, wenn die Eingabeinhalte nicht relevant sind. Legen Sie in der proactivity-Konfiguration proactive_audio auf true fest (erfordert v1beta).
Empathischer Dialog Nicht unterstützt Unterstützt. Das Modell passt seinen Antwortstil an die Ausdrucksweise und den Tonfall der Eingabe an. Legen Sie enable_affective_dialog in der Sitzungskonfiguration auf true fest (erfordert v1beta).

Informationen zur Migration von Gemini 2.5 Flash Live zu Gemini 3.1 Flash Live finden Sie im Migrationsleitfaden.

Verbindung herstellen

Im folgenden Beispiel wird gezeigt, wie Sie eine Verbindung mit einem API-Schlüssel erstellen:

Python

import asyncio
from google import genai

client = genai.Client()

model = "gemini-3.1-flash-live-preview"
config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started")
        # Send content...

if __name__ == "__main__":
    asyncio.run(main())

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        console.debug(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  console.debug("Session started");
  // Send content...

  session.close();
}

main();

Interaktionsmodalitäten

In den folgenden Abschnitten finden Sie Beispiele und Kontext für die verschiedenen Eingabe- und Ausgabemodalitäten, die in der Live API verfügbar sind.

Audio senden

Audio muss als rohe PCM-Daten gesendet werden (rohes 16-Bit-PCM-Audio, 16 kHz, Little Endian).

Python

# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)

JavaScript

// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});

Audioformate

Audiodaten in der Live API sind immer unkomprimiert, Little-Endian und 16-Bit-PCM. Die Audioausgabe erfolgt immer mit einer Abtastrate von 24 kHz. Die Eingabe-Audiodaten haben nativ eine Abtastrate von 16 kHz. Die Live API führt jedoch bei Bedarf ein Resampling durch, sodass jede Abtastrate gesendet werden kann. Um die Samplerate des eingegebenen Audiosignals anzugeben, legen Sie den MIME-Typ jedes Blob, das Audio enthält, auf einen Wert wie audio/pcm;rate=16000 fest.

Audio empfangen

Die Audioantworten des Modells werden als Datenblöcke empfangen.

Python

async for response in session.receive():
    if response.server_content and response.server_content.model_turn:
        for part in response.server_content.model_turn.parts:
            if part.inline_data:
                audio_data = part.inline_data.data
                # Process or play the audio data

JavaScript

// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data;
      // Process or play audioData (base64 encoded string)
    }
  }
}

SMS wird gesendet

Text kann mit send_realtime_input (Python) oder sendRealtimeInput (JavaScript) gesendet werden.

Python

await session.send_realtime_input(text="Hello, how are you?")

JavaScript

session.sendRealtimeInput({
  text: 'Hello, how are you?'
});

Video wird gesendet

Videoframes werden als einzelne Bilder (z. B. JPEG oder PNG) mit einer bestimmten Framerate (max. 1 Frame pro Sekunde) gesendet.

Python

# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
    video=types.Blob(
        data=frame,
        mime_type="image/jpeg"
    )
)

JavaScript

// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
  video: {
    data: frame.toString('base64'),
    mimeType: 'image/jpeg'
  }
});

Inkrementelle Aktualisierungen von Inhalten

Verwenden Sie inkrementelle Updates, um Texteingaben zu senden, Sitzungskontext herzustellen oder wiederherzustellen. Bei kurzen Kontexten können Sie Turn-by-Turn-Interaktionen senden, um die genaue Abfolge der Ereignisse darzustellen:

Python

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)

JavaScript

let inputTurns = [
  { "role": "user", "parts": [{ "text": "What is the capital of France?" }] },
  { "role": "model", "parts": [{ "text": "Paris" }] },
]

session.sendClientContent({ turns: inputTurns, turnComplete: false })

inputTurns = [{ "role": "user", "parts": [{ "text": "What is the capital of Germany?" }] }]

session.sendClientContent({ turns: inputTurns, turnComplete: