Die Gemini Live API ermöglicht die bidirektionale Interaktion mit Gemini-Modellen in Echtzeit und unterstützt Audio-, Video- und Texteingaben sowie native Audioausgaben. In diesem Leitfaden wird erläutert, wie Sie die API mit dem Google GenAI SDK auf Ihrem Server einbinden.
Übersicht
Die Gemini Live API verwendet WebSockets für die Echtzeitkommunikation. Das google-genai SDK bietet eine asynchrone Schnittstelle auf hoher Ebene zum Verwalten dieser Verbindungen.
Wichtige Konzepte:
- Sitzung: Eine dauerhafte Verbindung zum Modell.
- Konfiguration: Einrichten von Modalitäten (Audio/Text), Stimme und Systemanweisungen.
- Echtzeiteingabe: Senden von Audio- und Video-Frames als Blobs.
Verbindung zur Live API herstellen
So starten Sie eine Live API-Sitzung mit einem API-Schlüssel:
Python
import asyncio
from google import genai
client = genai.Client(api_key="YOUR_API_KEY")
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({ apiKey: "YOUR_API_KEY"});
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();
Text senden
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?'
});
Audio senden
Audio muss als unformatierte PCM-Daten gesendet werden (unformatiertes 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'
}
});
Ein Beispiel dafür, wie Sie Audio vom Clientgerät (z.B. dem Browser) abrufen, finden Sie im End-to-End-Beispiel auf GitHub.
Video senden
Video-Frames werden als einzelne Bilder (z.B. JPEG oder PNG) mit einer bestimmten Framerate gesendet (maximal 1 Frame pro Sekunde).
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'
}
});
Ein Beispiel dafür, wie Sie Video vom Clientgerät (z.B. dem Browser) abrufen, finden Sie im End-to-End-Beispiel auf GitHub.
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)
}
}
}
In der Beispiel-App auf GitHub erfahren Sie, wie Sie Audio auf Ihrem Server empfangen und es im Browser abspielen.
Text empfangen
Transkriptionen für Nutzereingaben und Modellausgaben sind im Serverinhalt verfügbar.
Python
async for response in session.receive():
content = response.server_content
if content:
if content.input_transcription:
print(f"User: {content.input_transcription.text}")
if content.output_transcription:
print(f"Gemini: {content.output_transcription.text}")
JavaScript
// Inside the onmessage callback
const content = response.serverContent;
if (content?.inputTranscription) {
console.log('User:', content.inputTranscription.text);
}
if (content?.outputTranscription) {
console.log('Gemini:', content.outputTranscription.text);
}
Toolaufrufe verarbeiten
Die API unterstützt Toolaufrufe (Funktionsaufrufe). Wenn das Modell einen Toolaufruf anfordert, müssen Sie die Funktion ausführen und die Antwort zurücksenden.
Python
async for response in session.receive():
if response.tool_call:
function_responses = []
for fc in response.tool_call.function_calls:
# 1. Execute the function locally
result = my_tool_function(**fc.args)
# 2. Prepare the response
function_responses.append(types.FunctionResponse(
name=fc.name,
id=fc.id,
response={"result": result}
))
# 3. Send the tool response back to the session
await session.send_tool_response(function_responses=function_responses)
JavaScript
// Inside the onmessage callback
if (response.toolCall) {
const functionResponses = [];
for (const fc of response.toolCall.functionCalls) {
const result = myToolFunction(fc.args);
functionResponses.push({
name: fc.name,
id: fc.id,
response: { result }
});
}
session.sendToolResponse({ functionResponses });
}
Nächste Schritte
- Im vollständigen Leitfaden zu den Funktionen der Live API Funktionen finden Sie Informationen zu den wichtigsten Funktionen und Konfigurationen, einschließlich der Erkennung von Sprachaktivitäten und nativen Audiofunktionen.
- Lesen Sie den Leitfaden zur Toolnutzung, um zu erfahren, wie Sie die Live API in Tools und Funktionsaufrufe einbinden.
- Im Leitfaden zur Sitzungsverwaltung erfahren Sie, wie Sie lange Unterhaltungen verwalten.
- Im Leitfaden zu kurzlebigen Tokens erfahren Sie mehr über die sichere Authentifizierung in Client-zu-Server-Anwendungen.
- Weitere Informationen zur zugrunde liegenden WebSockets API finden Sie in der WebSockets API-Referenz.