Live API

Die Live API ermöglicht bidirektionale Sprach- und Videointeraktionen mit Gemini bei niedriger Latenz. So können Sie live mit Gemini sprechen und gleichzeitig Videoeingaben streamen oder Ihren Bildschirm teilen. Mit der Live API können Sie Endnutzern natürliche, menschenähnliche Sprachunterhaltungen bieten.

Sie können die Live API in Google AI Studio ausprobieren. Wenn Sie die Live API in Google AI Studio verwenden möchten, wählen Sie Stream aus.

Funktionsweise der Live API

Streaming

Die Live API verwendet ein Streamingmodell über eine WebSocket. Wenn Sie mit der API interagieren, wird eine dauerhafte Verbindung hergestellt. Ihre Eingabe (Audio, Video oder Text) wird kontinuierlich an das Modell gestreamt und die Antwort des Modells (Text oder Audio) wird in Echtzeit über dieselbe Verbindung zurückgestreamt.

Dieses bidirektionale Streaming sorgt für eine geringe Latenz und unterstützt Funktionen wie die Erkennung von Sprachaktivitäten, die Toolnutzung und die Sprachgenerierung.

Live API – Übersicht

Weitere Informationen zur zugrunde liegenden WebSockets API finden Sie in der WebSockets API-Referenz.

Ausgabegenerierung

Die Live API verarbeitet multimodale Eingaben (Text, Audio, Video), um Text oder Audio in Echtzeit zu generieren. Es verfügt über einen integrierten Mechanismus zur Audiogenerierung. Je nach verwendeter Modellversion wird eine der beiden Audiogenerierungsmethoden verwendet:

  • Halbe Kaskade: Das Modell empfängt native Audioeingaben und verwendet eine spezielle Modellkaskade verschiedener Modelle, um die Eingabe zu verarbeiten und eine Audioausgabe zu generieren.
  • Nativ: In Gemini 2.5 wird die native Audiogenerierung eingeführt. Dabei wird die Audioausgabe direkt generiert, was zu natürlicher klingenden Audioinhalten, ausdrucksstärkeren Stimmen, einer besseren Wahrnehmung zusätzlichen Kontexts (z. B. Tonfall) und proaktiveren Antworten führt.

Live API für die App-Erstellung nutzen

Bevor du mit der Live API arbeitest, solltest du den Ansatz zur Audiogenerierung auswählen, der deinen Anforderungen am besten entspricht.

Verbindung herstellen

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

Python

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:
        print("Session started")

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

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const model = 'gemini-2.0-flash-live-001';
const config = { responseModalities: [Modality.TEXT] };

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

    // Send content...

    session.close();
}

main();

SMS senden und empfangen

So senden und empfangen Sie Nachrichten:

Python

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:
        message = "Hello, how are you?"
        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())

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const model = 'gemini-2.0-flash-live-001';
const config = { responseModalities: [Modality.TEXT] };

async function live() {
    const responseQueue = [];

    async function waitMessage() {
        let done = false;
        let message = undefined;
        while (!done) {
            message = responseQueue.shift();
            if (message) {
                done = true;
            } else {
                await new Promise((resolve) => setTimeout(resolve, 100));
            }
        }
        return message;
    }

    async function handleTurn() {
        const turns = [];
        let done = false;
        while (!done) {
            const message = await waitMessage();
            turns.push(message);
            if (message.serverContent && message.serverContent.turnComplete) {
                done = true;
            }
        }
        return turns;
    }

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

    const simple = 'Hello how are you?';
    session.sendClientContent({ turns: simple });

    const turns = await handleTurn();
    for (const turn of turns) {
        if (turn.text) {
            console.debug('Received text: %s\n', turn.text);
        }
        else if (turn.data) {
            console.debug('Received inline data: %s\n', turn.data);
        }
    }

    session.close();
}

async function main() {
    await live().catch((e) => console.error('got error', e));
}

main();

Audio senden und empfangen

Sie können Audio senden, indem Sie es in das Mono-Format 16-Bit PCM, 16 kHz konvertieren. In diesem Beispiel wird eine WAV-Datei gelesen und im richtigen Format gesendet:

Python

# Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav
# Install helpers for converting files: pip install librosa soundfile
import asyncio
import io
from pathlib import Path
from google import genai
from google.genai import types
import soundfile as sf
import librosa

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:

        buffer = io.BytesIO()
        y, sr = librosa.load("sample.wav", sr=16000)
        sf.write(buffer, y, sr, format='RAW', subtype='PCM_16')
        buffer.seek(0)
        audio_bytes = buffer.read()

        # If already in correct format, you can use this:
        # audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

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

JavaScript

// Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav
// Install helpers for converting files: npm install wavefile
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile';
const { WaveFile } = pkg;

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const model = 'gemini-2.0-flash-live-001';
const config = { responseModalities: [Modality.TEXT] };

async function live() {
    const responseQueue = [];

    async function waitMessage() {
        let done = false;
        let message = undefined;
        while (!done) {
            message = responseQueue.shift();
            if (message) {
                done = true;
            } else {
                await new Promise((resolve) => setTimeout(resolve, 100));
            }
        }
        return message;
    }

    async function handleTurn() {
        const turns = [];
        let done = false;
        while (!done) {
            const message = await waitMessage();
            turns.push(message);
            if (message.serverContent && message.serverContent.turnComplete) {
                done = true;
            }
        }
        return turns;
    }

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

    // Send Audio Chunk
    const fileBuffer = fs.readFileSync("sample.wav");

    // Ensure audio conforms to API requirements (16-bit PCM, 16kHz, mono)
    const wav = new WaveFile();
    wav.fromBuffer(fileBuffer);
    wav.toSampleRate(16000);
    wav.toBitDepth("16");
    const base64Audio = wav.toBase64();

    // If already in correct format, you can use this:
    // const fileBuffer = fs.readFileSync("sample.pcm");
    // const base64Audio = Buffer.from(fileBuffer).toString('base64');

    session.sendRealtimeInput(
        {
            audio: {
                data: base64Audio,
                mimeType: "audio/pcm;rate=16000"
            }
        }

    );

    const turns = await handleTurn();
    for (const turn of turns) {
        if (turn.text) {
            console.debug('Received text: %s\n', turn.text);
        }
        else if (turn.data) {
            console.debug('Received inline data: %s\n', turn.data);
        }
    }

    session.close();
}

async function main() {
    await live().catch((e) => console.error('got error', e));
}

main();

Sie können Audio erhalten, indem Sie AUDIO als Antwortmodalität festlegen. In diesem Beispiel werden die empfangenen Daten als WAV-Datei gespeichert:

Python

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 how are you?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in 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())

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const model = 'gemini-2.0-flash-live-001';
const config = { responseModalities: [Modality.AUDIO] };

async function live() {
    const responseQueue = [];

    async function waitMessage() {
        let done = false;
        let message = undefined;
        while (!done) {
            message = responseQueue.shift();
            if (message) {
                done = true;
            } else {
                await new Promise((resolve) => setTimeout(resolve, 100));
            }
        }
        return message;
    }

    async function handleTurn() {
        const turns = [];
        let done = false;
        while (!done) {
            const message = await waitMessage();
            turns.push(message);
            if (message.serverContent && message.serverContent.turnComplete) {
                done = true;
            }
        }
        return turns;
    }

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

    const simple = 'Hello how are you?';
    session.sendClientContent({ turns: simple });

    const turns = await handleTurn();

    // Combine audio data strings and save as wave file
    const combinedAudio = turns.reduce((acc, turn) => {
        if (turn.data) {
            const buffer = Buffer.from(turn.data, 'base64');
            const intArray = new Int16Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / Int16Array.BYTES_PER_ELEMENT);
            return acc.concat(Array.from(intArray));
        }
        return acc;
    }, []);

    const audioBuffer = new Int16Array(combinedAudio);

    const wf = new WaveFile();
    wf.fromScratch(1, 24000, '16', audioBuffer);
    fs.writeFileSync('output.wav', wf.toBuffer());

    session.close();
}

async function main() {
    await live().catch((e) => console.error('got error', e));
}

main();

Audioformate

Audiodaten in der Live API sind immer roh, Little Endian und 16-Bit-PCM. Für die Audioausgabe wird immer eine Abtastrate von 24 kHz verwendet. Die Eingabeaudiodaten haben standardmäßig eine Abtastrate von 16 kHz. Die Live API nimmt bei Bedarf jedoch eine Neuberechnung vor, damit jede Abtastrate gesendet werden kann. Um die Abtastrate der Eingabeaudiodatei zu übertragen, legen Sie den MIME-Typ jedes Blobs mit Audioinhalten auf einen Wert wie audio/pcm;rate=16000 fest.

Audiotranskripte empfangen

Sie können die Transkription der Audioausgabe des Modells aktivieren, indem Sie output_audio_transcription in der Einrichtungskonfiguration senden. 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())

Sie können die Transkription der Audioeingabe aktivieren, indem Sie in der Einrichtungskonfiguration input_audio_transcription senden.

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": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {"disabled": True},
        "activity_handling": "NO_INTERRUPTION",
    },
    "input_audio_transcription": {},
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_data = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(activity_start=types.ActivityStart())
        await session.send_realtime_input(
            audio=types.Blob(data=audio_data, mime_type='audio/pcm;rate=16000')
        )
        await session.send_realtime_input(activity_end=types.ActivityEnd())

        async for msg in session.receive():
            if msg.server_content.input_transcription:
                print('Transcript:', msg.server_content.input_transcription.text)

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

Audio- und Videostreaming

Systemanweisungen

Mit Systemanweisungen können Sie das Verhalten eines Modells basierend auf 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:

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)

JSON

{
  "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 und Sprache ä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:

Python

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

JSON

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

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

Native Audioausgabe

Über die Live API können Sie auch auf Modelle zugreifen, die neben nativer Audioeingabe auch native Audioausgabe ermöglichen. Dies ermöglicht eine bessere Audioqualität mit besserem Tempo, natürlicher Stimme, Ausführlichkeit und Stimmung.

Die native Audioausgabe wird von den folgenden nativen Audiomodellen unterstützt:

  • gemini-2.5-flash-preview-native-audio-dialog
  • gemini-2.5-flash-exp-native-audio-thinking-dialog

Native Audioausgabe verwenden

Wenn Sie die native Audioausgabe verwenden möchten, konfigurieren Sie eines der nativen Audiomodelle und legen Sie für response_modalities den Wert AUDIO fest.

Ein vollständiges Beispiel finden Sie unter Audio senden und empfangen.

Python

model = "gemini-2.5-flash-preview-native-audio-dialog"
config = types.LiveConnectConfig(response_modalities=["AUDIO"])

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio input and receive audio

JavaScript

const model = 'gemini-2.5-flash-preview-native-audio-dialog';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

    const session = await ai.live.connect({
        model: model,
        config: config,
        callbacks: ...,
    });

    // Send audio input and receive audio

    session.close();
}

main();

Dialog mit Emotionen

Mit dieser Funktion kann Gemini seinen Antwortstil an den Ausdruck und Ton der Eingabe anpassen.

Wenn Sie einen affektiven Dialog verwenden möchten, legen Sie in der Einrichtungsnachricht die API-Version auf v1alpha und enable_affective_dialog auf true fest:

Python

client = genai.Client(api_key="GOOGLE_API_KEY", http_options={"api_version": "v1alpha"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True
)

JavaScript

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY", httpOptions: {"apiVersion": "v1alpha"} });

const config = {
    responseModalities: [Modality.AUDIO],
    enableAffectiveDialog: true
};

Hinweis: Affektiver Dialog wird derzeit nur von den nativen Audioausgabemodellen unterstützt.

Proaktive Audiooptimierung

Wenn diese Funktion aktiviert ist, kann Gemini proaktiv entscheiden, nicht zu antworten, wenn die Inhalte nicht relevant sind.

Wenn Sie sie verwenden möchten, legen Sie die API-Version auf v1alpha fest, konfigurieren Sie das Feld proactivity in der Einrichtungsnachricht und legen Sie proactive_audio auf true fest:

Python

client = genai.Client(api_key="GOOGLE_API_KEY", http_options={"api_version": "v1alpha"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity={'proactive_audio': True}
)

JavaScript

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY", httpOptions: {"apiVersion": "v1alpha"} });

const config = {
    responseModalities: [Modality.AUDIO],
    proactivity: { proactiveAudio: true }
}

Proaktive Audioinhalte werden derzeit nur von den nativen Audioausgabemodellen unterstützt.

Native Audioausgabe mit Nachdenken

Die native Audioausgabe unterstützt Denkfunktionen, die über ein separates Modell gemini-2.5-flash-exp-native-audio-thinking-dialog verfügbar sind.

Ein vollständiges Beispiel finden Sie unter Audio senden und empfangen.

Python 

model = "gemini-2.5-flash-exp-native-audio-thinking-dialog"
config = types.LiveConnectConfig(response_modalities=["AUDIO"])

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio input and receive audio

JavaScript

const model = 'gemini-2.5-flash-exp-native-audio-thinking-dialog';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

    const session = await ai.live.connect({
        model: model,
        config: config,
        callbacks: ...,
    });

    // Send audio input and receive audio

    session.close();
}

main();

Tool mit der Live API verwenden

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

Unterstützte Tools

Hier finden Sie einen kurzen Überblick über die für jedes Modell verfügbaren Tools:

Tool Kaskadenmodelle
gemini-2.0-flash-live-001		 gemini-2.5-flash-preview-native-audio-dialog gemini-2.5-flash-exp-native-audio-thinking-dialog
Suche Ja Ja Ja
Funktionsaufrufe Ja Ja Nein
Codeausführung Ja Nein Nein
URL-Kontext Ja Nein Nein

Funktionsaufrufe

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

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.

Asynchroner Funktionsaufruf

Standardmäßig wird die Ausführung pausiert, bis die Ergebnisse jedes Funktionsaufrufs verfügbar sind. So wird eine sequenzielle Verarbeitung sichergestellt. Das bedeutet, dass Sie während der Ausführung der Funktionen nicht mehr mit dem Modell interagieren können.

Wenn Sie die Unterhaltung nicht blockieren möchten, können Sie dem Modell mitteilen, dass die Funktionen asynchron ausgeführt werden sollen.

Dazu müssen Sie den Funktionsdefinitionen zuerst ein behavior hinzufügen:

  # Non-blocking function definitions
  turn_on_the_lights = {"name": "turn_on_the_lights", "behavior": "NON_BLOCKING"} # turn_on_the_lights will run asynchronously
  turn_off_the_lights = {"name": "turn_off_the_lights"} # turn_off_the_lights will still pause all interactions with the model

NON-BLOCKING sorgt dafür, dass die Funktion asynchron ausgeführt wird, während Sie weiterhin mit dem Modell interagieren können.

Anschließend müssen Sie dem Modell mit dem Parameter scheduling mitteilen, wie es sich verhalten soll, wenn es FunctionResponse empfängt. Es kann folgende Funktionen haben:

  • Unterbricht die Ausführung und teilt Ihnen sofort die Antwort mit, die es erhalten hat (scheduling="INTERRUPT"),
  • Warten Sie, bis der Vorgang abgeschlossen ist (scheduling="WHEN_IDLE").
  • Sie können auch nichts tun und dieses Wissen später in der Diskussion nutzen. scheduling="SILENT"
# Non-blocking function definitions
  function_response = types.FunctionResponse(
      id=fc.id,
      name=fc.name,
      response={
          "result": "ok",
          "scheduling": "INTERRUPT" # Can also be WHEN_IDLE or SILENT
      }
  )

Codeausführung

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}

Umgang mit Unterbrechungen

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

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 alle im Cache gespeicherten Audioinhalte 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
from google.genai import types

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 Nachrichten der Reihe nach zum Modellkontext hinzufügt, ist send_realtime_input für eine schnelle Reaktionszeit optimiert, was auf Kosten 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

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

Wenn Sie längere Sitzungen ermöglichen und ein abruptes Verbindungsende vermeiden möchten, können Sie die Kontextfensterkomprimierung aktivieren, indem Sie das Feld contextWindowCompression als Teil der Sitzungskonfiguration festlegen.

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

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

Nachricht 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

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

Beschränkungen

Berücksichtigen Sie bei der Planung Ihres Projekts die folgenden Einschränkungen der Live API.

Antwortmodalitäten

Sie können in der Sitzungskonfiguration nur eine Antwortmodalität (TEXT oder AUDIO) pro Sitzung festlegen. Wenn Sie beides festlegen, wird eine Konfigurationsfehlermeldung ausgegeben. Das bedeutet, dass Sie das Modell so konfigurieren können, 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 vorgeschaltet 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:

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:

Nächste Schritte