Jest to obszerny przewodnik, który zawiera informacje o możliwościach i konfiguracjach dostępnych w interfejsie Live API. Na stronie Pierwsze kroki z interfejsem Live API znajdziesz omówienie i przykładowy kod dla typowych przypadków użycia.
Zanim zaczniesz
- Zapoznaj się z podstawowymi pojęciami: jeśli jeszcze tego nie zrobiono, najpierw przeczytaj stronę Wprowadzenie do interfejsu Live API . Poznasz podstawowe zasady działania interfejsu Live API, jego działanie i różne metody implementacji.
- Wypróbuj interfejs Live API w AI Studio: przed rozpoczęciem tworzenia możesz wypróbować interfejs Live API w Google AI Studio. Aby używać interfejsu Live API w Google AI Studio, wybierz Stream (Strumień).
Porównanie modeli
W tej tabeli zestawiono najważniejsze różnice między modelami Gemini 3.1 Flash Live Preview i Gemini 2.5 Flash Live Preview:
| Funkcja | Gemini 3.1 Flash Live (wersja testowa) | Gemini 2.5 Flash Live Preview |
|---|---|---|
| Myślenie | Wykorzystuje thinkingLevel do kontrolowania głębokości myślenia za pomocą ustawień takich jak minimal, low, medium i high. Domyślnie jest ustawiona wartość minimal, aby optymalizować pod kątem najmniejszego opóźnienia. Zobacz Poziomy i budżety. |
Używa parametru thinkingBudget do ustawienia liczby tokenów myślenia. Dynamiczne myślenie jest domyślnie włączone. Aby wyłączyć tę opcję, ustaw wartość thinkingBudget na 0. Zobacz Poziomy i budżety. |
| Otrzymywanie odpowiedzi | Pojedyncze zdarzenie serwera może zawierać jednocześnie wiele części treści (np. inlineData i transkrypcję). Aby uniknąć pominięcia treści, upewnij się, że kod przetwarza wszystkie części każdego zdarzenia. |
Każde zdarzenie serwera zawiera tylko jedną część treści. Części są dostarczane w ramach osobnych zdarzeń. |
| Treści klienta | send_client_content jest obsługiwane tylko w przypadku wypełniania początkowej historii kontekstu (wymaga ustawienia initial_history_in_client_content w konfiguracji sesji). Aby wysyłać powiadomienia tekstowe w trakcie rozmowy, użyj send_realtime_input. |
send_client_content jest obsługiwany w trakcie rozmowy, aby wysyłać przyrostowe aktualizacje treści i ustalać kontekst. |
| Pokrycie zakrętu | Domyślna wartość to TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO. Tura modelu obejmuje wykrytą aktywność audio i wszystkie klatki wideo. |
Domyślna wartość to TURN_INCLUDES_ONLY_ACTIVITY. Tura modelu obejmuje tylko wykrytą aktywność. |
Niestandardowe VAD (activity_start/activity_end) |
Obsługiwane Wyłącz automatyczne wykrywanie aktywności głosowej i ręcznie wysyłaj wiadomości activityStart i activityEnd, aby kontrolować granice tur. |
Obsługiwane Wyłącz automatyczne wykrywanie aktywności głosowej i ręcznie wysyłaj wiadomości activityStart i activityEnd, aby kontrolować granice tur. |
| Automatyczna konfiguracja VAD | Obsługiwane Skonfiguruj parametry takie jak start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms i silence_duration_ms. |
Obsługiwane Skonfiguruj parametry takie jak start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms i silence_duration_ms. |
Asynchroniczne wywoływanie funkcji (behavior: NON_BLOCKING) |
Nieobsługiwane Wywoływanie funkcji jest tylko sekwencyjne. Model nie zacznie odpowiadać, dopóki nie wyślesz odpowiedzi narzędzia. | Obsługiwane Ustaw wartość behavior na NON_BLOCKING w deklaracji funkcji, aby model mógł kontynuować interakcję podczas jej działania. Określ, jak model ma obsługiwać odpowiedzi, za pomocą parametru scheduling (INTERRUPT, WHEN_IDLE lub SILENT). |
| Proaktywny dźwięk | Nieobsługiwane | Obsługiwane Po włączeniu tej funkcji model może z własnej inicjatywy nie odpowiadać, jeśli treść wejściowa jest nieistotna. Ustaw wartość proactive_audio na true w konfiguracji proactivity (wymaga v1beta). |
| Afektywny dialog | Nieobsługiwane | Obsługiwane Model dostosowuje styl odpowiedzi do ekspresji i tonu rozmówcy. Ustaw enable_affective_dialog na true w konfiguracji sesji (wymaga v1beta). |
Aby przeprowadzić migrację z Gemini 2.5 Flash Live na Gemini 3.1 Flash Live, zapoznaj się z przewodnikiem po migracji.
Nawiązywanie połączenia
Poniższy przykład pokazuje, jak utworzyć połączenie za pomocą klucza interfejsu API:
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();
Rodzaje interakcji
W kolejnych sekcjach znajdziesz przykłady i kontekst różnych trybów wejścia i wyjścia dostępnych w interfejsie Live API.
Wysyłanie dźwięku
Dźwięk musi być przesyłany jako nieprzetworzone dane PCM (nieprzetworzone 16-bitowe audio PCM, 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'
}
});
Formaty audio
Dane audio w interfejsie Live API są zawsze w formacie surowym, little-endian, 16-bitowym PCM. Wyjście audio zawsze korzysta z częstotliwości próbkowania 24 kHz. Dźwięk wejściowy
ma natywną częstotliwość próbkowania 16 kHz, ale interfejs Live API w razie potrzeby zmieni częstotliwość próbkowania,
więc można wysłać dowolną częstotliwość próbkowania. Aby przekazać częstotliwość próbkowania dźwięku wejściowego, ustaw typ MIME każdego obiektu Blob zawierającego dźwięk na wartość taką jak audio/pcm;rate=16000.
Odbieranie dźwięku
Odpowiedzi dźwiękowe modelu są odbierane jako fragmenty danych.
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)
}
}
}
Wysyłam tekst
Tekst można wysyłać za pomocą send_realtime_input (Python) lub sendRealtimeInput (JavaScript).
Python
await session.send_realtime_input(text="Hello, how are you?")
JavaScript
session.sendRealtimeInput({
text: 'Hello, how are you?'
});
Wysyłam film
Klatki wideo są wysyłane jako pojedyncze obrazy (np. JPEG lub PNG) z określoną liczbą klatek na sekundę (maksymalnie 1 klatka na sekundę).
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'
}
});
Aktualizacje przyrostowe treści
Używaj aktualizacji przyrostowych, aby wysyłać tekst, tworzyć kontekst sesji lub przywracać kontekst sesji. W przypadku krótkich kontekstów możesz wysyłać interakcje krok po kroku, aby odzwierciedlić dokładną sekwencję zdarzeń:
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: true })
W przypadku dłuższych kontekstów zaleca się podanie pojedynczego podsumowania wiadomości, aby zwolnić okno kontekstowe na kolejne interakcje. Aby poznać inną metodę ładowania kontekstu sesji, zobacz Wznawianie sesji.
Zapisy tekstowe
Oprócz odpowiedzi modelu możesz również otrzymać transkrypcje zarówno sygnału wyjściowego, jak i sygnału wejściowego.
Aby włączyć transkrypcję wyjścia audio modelu, w konfiguracji wysyłania ustawień wyślij output_audio_transcription. Język transkrypcji jest wnioskowany na podstawie odpowiedzi modelu.
Python
import asyncio
from google import genai
from google.genai import types
client = genai.Client()
model = "gemini-3.1-flash-live-preview"
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())
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview'