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
Die Live API bietet neue Funktionen und Möglichkeiten.
Neue Funktionen:
- Zwei neue Stimmen und 30 neue Sprachen mit konfigurierbarer Ausgabesprache
- Konfigurierbare Bildauflösungen (66/256 Token)
- Konfigurierbare Abdeckung von Abbiegeversuchen: Alle Eingaben werden immer oder nur gesendet, wenn der Nutzer spricht.
- Konfigurieren, ob Eingaben das Modell unterbrechen sollen
- Konfigurierbare Erkennung der Sprachaktivitäten und neue Clientereignisse für das Signal zum Ende eines Sprachbeitrags
- Tokenanzahl
- Ein Clientereignis, das das Ende des Streams signalisiert
- Text streaming
- Konfigurierbare Sitzungswiederaufnahme, wobei Sitzungsdaten 24 Stunden lang auf dem Server gespeichert werden
- Unterstützung für längere Sitzungen mit einem gleitenden Kontextfenster
Ereignisse für neue Kunden:
- Ende des Audiostreams / Mikrofon geschlossen
- Start-/Endereignisse für die manuelle Steuerung von Abbiegeverläufen
Neue Serverereignisse:
- Benachrichtigung, dass eine Sitzung neu gestartet werden muss
- Generierung abgeschlossen
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.
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", http_options={'api_version': 'v1alpha'})
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:
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 ä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"
}
}
}
Funktionsaufrufe verwenden
Sie können Tools mit der 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_client_content(
turns={
"role": "user",
"parts": [{"text": "Turn the lights down to a romantic level"}],
},
turn_complete=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
Erkennung der Sprachaktivitäten konfigurieren
Standardmäßig führt das Modell automatisch eine Sprachaktivitätserkennung (VAD) für einen kontinuierlichen Audioeingangsstream durch. 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.
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.
Der SDK-Support für diese Funktion wird in den kommenden Wochen verfügbar sein.
Tokenanzahl abrufen
Die Gesamtzahl der verwendeten Tokens findest du im Feld usageMetadata der zurückgegebenen Servernachricht.
from google.genai import types
async with client.aio.live.connect(
model='gemini-2.0-flash-live-001',
config=types.LiveConnectConfig(
response_modalities=['AUDIO'],
),
) as session:
# Session connected
while True:
await session.send_client_content(
turns=types.Content(role='user', parts=[types.Part(text='Hello world!')])
)
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}')
# 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
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 Wiederaufnahme-Token als SessionResumptionConfig.handle der nachfolgenden Verbindung übergeben.
from google.genai import types
print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
model="gemini-2.0-flash-live-001",
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:
# Session connected
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
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.
Benachrichtigung erhalten, wenn die Generierung abgeschlossen ist
Der Server sendet die Nachricht generationComplete, die signalisiert, dass die Antwort vom Modell generiert wurde.
Komprimierung des Kontextfensters aktivieren
Wenn Sie längere Sitzungen ermöglichen und abrupte Verbindungsabbrüche 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(),
)
),
)
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,
)
Beschränkungen
Beachten Sie bei der Planung Ihres Projekts die folgenden Einschränkungen der Live API und Gemini 2.0.
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.
Verlaufszeitraum
Für eine Sitzung gilt ein Kontextfensterlimit von 32.000 Tokens.
Integrationen externer Anbieter
Für die Bereitstellung von Web- und mobilen Apps stehen folgende Optionen zur Verfügung: