Live API memungkinkan interaksi suara dan video dua arah dengan latensi rendah dengan Gemini, sehingga Anda dapat berbicara dengan Gemini secara live sekaligus melakukan streaming input video atau berbagi layar. Dengan menggunakan Live API, Anda dapat memberikan pengalaman percakapan suara alami layaknya manusia kepada pengguna akhir.
Anda dapat mencoba Live API di Google AI Studio. Untuk menggunakan Live API di Google AI Studio, pilih Stream.
Cara kerja Live API
Streaming
Live API menggunakan model streaming melalui koneksi WebSocket. Saat Anda berinteraksi dengan API, koneksi persisten akan dibuat. Input Anda (audio, video, atau teks) di-streaming secara terus-menerus ke model, dan respons model (teks atau audio) di-streaming kembali secara real-time melalui koneksi yang sama.
Streaming dua arah ini memastikan latensi rendah dan mendukung fitur seperti deteksi aktivitas suara, penggunaan alat, dan pembuatan ucapan.
Untuk informasi selengkapnya tentang WebSockets API yang mendasarinya, lihat Referensi WebSockets API.
Pembuatan output
Live API memproses input multimodal (teks, audio, video) untuk menghasilkan teks atau audio secara real-time. Model ini dilengkapi dengan mekanisme bawaan untuk membuat audio dan bergantung pada versi model yang Anda gunakan, model ini menggunakan salah satu dari dua metode pembuatan audio:
- Half cascade: Model menerima input audio native dan menggunakan cascade model khusus dari model yang berbeda untuk memproses input dan menghasilkan output audio.
- Native: Gemini 2.5 memperkenalkan pembuatan audio native, yang langsung menghasilkan output audio, memberikan audio yang terdengar lebih alami, suara yang lebih ekspresif, lebih banyak kesadaran terhadap konteks tambahan, misalnya, nada, dan respons yang lebih proaktif.
Membangun dengan Live API
Sebelum Anda mulai mem-build dengan Live API, pilih pendekatan pembuatan audio yang paling sesuai dengan kebutuhan Anda.
Membuat koneksi
Contoh berikut menunjukkan cara membuat koneksi dengan kunci API:
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();
Mengirim dan menerima teks
Berikut cara mengirim dan menerima teks:
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();
Mengirim dan menerima audio
Anda dapat mengirim audio dengan mengonversinya ke format PCM 16-bit, 16 kHz, mono. Contoh ini membaca file WAV dan mengirimkannya dalam format yang benar:
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();
Anda dapat menerima audio dengan menetapkan AUDIO
sebagai modalitas respons. Contoh ini
menyimpan data yang diterima sebagai file WAV:
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();
Format audio
Data audio di Live API selalu berupa PCM 16-bit mentah, little-endian. Output audio selalu menggunakan frekuensi sampling 24 kHz. Audio input
adalah 16 kHz secara native, tetapi Live API akan mengambil sampel ulang jika diperlukan
sehingga frekuensi sampel apa pun dapat dikirim. Untuk menyampaikan frekuensi sampel audio input, tetapkan
jenis MIME dari setiap Blob yang berisi audio ke nilai
seperti audio/pcm;rate=16000
.
Menerima transkripsi audio
Anda dapat mengaktifkan transkripsi output audio model dengan mengirim
output_audio_transcription
dalam konfigurasi penyiapan. Bahasa transkripsi
diinferensi dari respons model.
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())
Anda dapat mengaktifkan transkripsi input audio dengan mengirimkan
input_audio_transcription
dalam konfigurasi penyiapan.
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())
Streaming audio dan video
Petunjuk sistem
Petunjuk sistem memungkinkan Anda mengarahkan perilaku model berdasarkan kebutuhan dan kasus penggunaan tertentu. Petunjuk sistem dapat ditetapkan dalam konfigurasi penyiapan dan akan tetap berlaku selama seluruh sesi.
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"],
}
Update konten inkremental
Gunakan update inkremental untuk mengirim input teks, menetapkan konteks sesi, atau memulihkan konteks sesi. Untuk konteks singkat, Anda dapat mengirim interaksi per belokan untuk mewakili urutan peristiwa yang tepat:
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
}
}
Untuk konteks yang lebih panjang, sebaiknya berikan satu ringkasan pesan untuk mengosongkan jendela konteks untuk interaksi berikutnya.
Mengubah suara dan bahasa
Live API mendukung suara berikut: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, dan Zephyr.
Untuk menentukan suara, tetapkan nama suara dalam objek speechConfig
sebagai bagian
dari konfigurasi sesi:
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"
}
}
}
Live API mendukung beberapa bahasa.
Untuk mengubah bahasa, tetapkan kode bahasa dalam objek speechConfig
sebagai bagian dari konfigurasi sesi:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
language_code="de-DE",
)
)
Output audio native
Melalui Live API, Anda juga dapat mengakses model yang memungkinkan output audio native selain input audio native. Hal ini memungkinkan output audio berkualitas lebih tinggi dengan kecepatan, kealamian suara, kepanjangan, dan suasana hati yang lebih baik.
Output audio native didukung oleh model audio native berikut:
gemini-2.5-flash-preview-native-audio-dialog
gemini-2.5-flash-exp-native-audio-thinking-dialog
Cara menggunakan output audio native
Untuk menggunakan output audio native, konfigurasikan salah satu model audio native
dan tetapkan response_modalities
ke AUDIO
.
Lihat Mengirim dan menerima audio untuk contoh lengkap.
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 afektif
Fitur ini memungkinkan Gemini menyesuaikan gaya responsnya dengan ekspresi dan nada input.
Untuk menggunakan dialog afektif, tetapkan versi API ke v1alpha
dan tetapkan
enable_affective_dialog
ke true
dalam pesan penyiapan:
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
};
Perhatikan bahwa dialog afektif saat ini hanya didukung oleh model output audio native.
Audio proaktif
Jika fitur ini diaktifkan, Gemini dapat secara proaktif memutuskan untuk tidak merespons jika konten tidak relevan.
Untuk menggunakannya, tetapkan versi API ke v1alpha
dan konfigurasikan kolom proactivity
dalam pesan penyiapan, lalu tetapkan
proactive_audio
ke true
:
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 }
}
Perhatikan bahwa audio proaktif saat ini hanya didukung oleh model output audio native.
Output audio native dengan pemikiran
Output audio native mendukung kemampuan berpikir,
yang tersedia melalui model terpisah gemini-2.5-flash-exp-native-audio-thinking-dialog
.
Lihat Mengirim dan menerima audio untuk contoh lengkap.
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();
Penggunaan alat dengan Live API
Anda dapat menentukan alat seperti Panggilan fungsi, Eksekusi kode, dan Google Penelusuran dengan Live API.
Ringkasan alat yang didukung
Berikut adalah ringkasan singkat tentang alat yang tersedia untuk setiap model:
Alat | Model bersusungemini-2.0-flash-live-001 |
gemini-2.5-flash-preview-native-audio-dialog |
gemini-2.5-flash-exp-native-audio-thinking-dialog |
---|---|---|---|
Penelusuran | Ya | Ya | Ya |
Panggilan fungsi | Ya | Ya | Tidak |
Eksekusi kode | Ya | Tidak | Tidak |
Konteks URL | Ya | Tidak | Tidak |
Panggilan fungsi
Anda dapat menentukan deklarasi fungsi sebagai bagian dari konfigurasi sesi. Lihat Tutorial panggilan fungsi untuk mempelajari lebih lanjut.
Setelah menerima panggilan alat, klien harus merespons dengan daftar
objek FunctionResponse
menggunakan metode session.send_tool_response
.
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())
Dari satu perintah, model dapat menghasilkan beberapa panggilan fungsi dan kode yang diperlukan untuk merantai outputnya. Kode ini dieksekusi di lingkungan sandbox, yang menghasilkan pesan BidiGenerateContentToolCall berikutnya.
Panggilan fungsi asinkron
Secara default, eksekusi dijeda hingga hasil setiap panggilan fungsi tersedia, yang memastikan pemrosesan berurutan. Artinya, Anda tidak akan dapat terus berinteraksi dengan model saat fungsi dijalankan.
Jika tidak ingin memblokir percakapan, Anda dapat memberi tahu model untuk menjalankan fungsi secara asinkron.
Untuk melakukannya, Anda harus menambahkan behavior
ke definisi
fungsi terlebih dahulu:
# 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
akan memastikan fungsi berjalan secara asinkron saat Anda dapat
terus berinteraksi dengan model.
Kemudian, Anda perlu memberi tahu model cara berperilaku saat menerima
FunctionResponse
menggunakan parameter scheduling
. Hal ini dapat:
- Mengganggu aktivitasnya dan langsung memberi tahu Anda tentang respons yang didapatnya
(
scheduling="INTERRUPT"
), - Tunggu hingga selesai melakukan tindakan yang sedang dilakukan
(
scheduling="WHEN_IDLE"
), - Atau tidak melakukan apa pun dan menggunakan pengetahuan tersebut nanti dalam diskusi
(
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
}
)
Eksekusi kode
Anda dapat menentukan eksekusi kode sebagai bagian dari konfigurasi sesi. Lihat Tutorial eksekusi kode untuk mempelajari lebih lanjut.
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())
Grounding dengan Google Penelusuran
Anda dapat mengaktifkan Grounding dengan Google Penelusuran sebagai bagian dari konfigurasi sesi. Lihat Tutorial pentanahan untuk mempelajari lebih lanjut.
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())
Menggabungkan beberapa alat
Anda dapat menggabungkan beberapa alat dalam Live API:
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}
Menangani gangguan
Pengguna dapat mengganggu output model kapan saja. Saat Deteksi aktivitas suara (VAD) mendeteksi gangguan, pembuatan yang sedang berlangsung akan dibatalkan dan dihapus. Hanya informasi yang telah dikirim ke klien yang dipertahankan dalam histori sesi. Server kemudian mengirimkan pesan BidiGenerateContentServerContent untuk melaporkan gangguan.
Selain itu, server Gemini akan menghapus panggilan fungsi yang tertunda dan mengirim
pesan BidiGenerateContentServerContent
dengan ID panggilan yang dibatalkan.
async for response in session.receive():
if response.server_content.interrupted is True:
# The generation was interrupted
Deteksi aktivitas suara (VAD)
Anda dapat mengonfigurasi atau menonaktifkan deteksi aktivitas suara (VAD).
Menggunakan VAD otomatis
Secara default, model akan otomatis melakukan VAD pada
streaming input audio yang berkelanjutan. VAD dapat dikonfigurasi dengan kolom realtimeInputConfig.automaticActivityDetection
dari konfigurasi penyiapan.
Saat streaming audio dijeda selama lebih dari satu detik (misalnya,
karena pengguna menonaktifkan mikrofon), peristiwa
audioStreamEnd
harus dikirim untuk menghapus audio yang di-cache. Klien dapat melanjutkan pengiriman
data audio kapan saja.
# 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())
Dengan send_realtime_input
, API akan merespons audio secara otomatis berdasarkan
VAD. Meskipun send_client_content
menambahkan pesan ke konteks model secara
berurutan, send_realtime_input
dioptimalkan untuk responsivitas dengan mengorbankan
urutan deterministik.
Mengonfigurasi VAD otomatis
Untuk kontrol yang lebih besar atas aktivitas VAD, Anda dapat mengonfigurasi parameter berikut. Lihat referensi API untuk mengetahui info selengkapnya.
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,
}
}
}
Menonaktifkan VAD otomatis
Atau, VAD otomatis dapat dinonaktifkan dengan menetapkan
realtimeInputConfig.automaticActivityDetection.disabled
ke true
dalam pesan
penyiapan. Dalam konfigurasi ini, klien bertanggung jawab untuk mendeteksi ucapan
pengguna dan mengirim
pesan activityStart
dan activityEnd
pada waktu yang tepat. audioStreamEnd
tidak dikirim dalam
konfigurasi ini. Sebagai gantinya, gangguan streaming apa pun ditandai dengan
pesan activityEnd
.
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())
# ...
Jumlah token
Anda dapat menemukan jumlah total token yang digunakan di kolom usageMetadata dari pesan server yang ditampilkan.
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}")
Memperpanjang durasi sesi
Durasi sesi maksimum dapat diperpanjang menjadi tanpa batas dengan dua mekanisme:
Selain itu, Anda akan menerima pesan GoAway sebelum sesi berakhir, sehingga Anda dapat mengambil tindakan lebih lanjut.
Kompresi jendela konteks
Untuk mengaktifkan sesi yang lebih lama, dan menghindari penghentian koneksi secara tiba-tiba, Anda dapat mengaktifkan kompresi jendela konteks dengan menetapkan kolom contextWindowCompression sebagai bagian dari konfigurasi sesi.
Di ContextWindowCompressionConfig, Anda dapat mengonfigurasi mekanisme jendela geser dan jumlah token yang memicu kompresi.
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(),
)
),
)
Melanjutkan sesi
Untuk mencegah penghentian sesi saat server mereset koneksi WebSocket secara berkala, konfigurasikan kolom sessionResumption dalam konfigurasi penyiapan.
Meneruskan konfigurasi ini akan menyebabkan
server mengirim pesan SessionResumptionUpdate, yang dapat digunakan untuk melanjutkan sesi dengan meneruskan token
lanjutan terakhir sebagai SessionResumptionConfig.handle
koneksi berikutnya.
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())
Menerima pesan sebelum sesi terputus
Server mengirim pesan GoAway yang menandakan bahwa koneksi saat ini akan segera dihentikan. Pesan ini menyertakan timeLeft, yang menunjukkan waktu yang tersisa dan memungkinkan Anda mengambil tindakan lebih lanjut sebelum koneksi dihentikan sebagai ABORTED.
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)
Menerima pesan saat pembuatan selesai
Server mengirimkan pesan generationComplete yang menandakan bahwa model telah selesai membuat respons.
async for response in session.receive():
if response.server_content.generation_complete is True:
# The generation is complete
Resolusi media
Anda dapat menentukan resolusi media untuk media input dengan menetapkan
kolom mediaResolution
sebagai bagian dari konfigurasi sesi:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)
Batasan
Pertimbangkan batasan Live API berikut saat Anda merencanakan project.
Modalitas respons
Anda hanya dapat menetapkan satu modalitas respons (TEXT
atau AUDIO
) per sesi dalam
konfigurasi sesi. Menetapkan keduanya akan menghasilkan pesan error konfigurasi. Artinya,
Anda dapat mengonfigurasi model untuk merespons dengan teks atau audio,
tetapi tidak keduanya dalam sesi yang sama.
Autentikasi klien
Live API hanya menyediakan autentikasi server ke server dan tidak direkomendasikan untuk penggunaan klien langsung. Input klien harus dirutekan melalui server aplikasi perantara untuk autentikasi aman dengan Live API.
Durasi sesi
Durasi sesi dapat diperpanjang menjadi tidak terbatas dengan mengaktifkan kompresi sesi. Tanpa kompresi, sesi audio saja dibatasi hingga 15 menit, dan sesi audio plus video dibatasi hingga 2 menit. Jika batas ini terlampaui tanpa kompresi, koneksi akan dihentikan.
Selain itu, Anda dapat mengonfigurasi lanjutan sesi untuk memungkinkan klien melanjutkan sesi yang dihentikan.
Jendela konteks
Sesi memiliki batas periode konteks sebesar:
- 128 ribu token untuk model output audio native
- 32 ribu token untuk model Live API lainnya
Bahasa yang didukung
Live API mendukung bahasa berikut.
Language | Kode BCP-47 |
---|---|
Jerman (Jerman) | de-DE |
Inggris (Australia) | en-AU |
Inggris (Inggris Raya) | en-GB |
Inggris (India) | en-IN |
Inggris (AS) | en-US |
Spanyol (Amerika Serikat) | es-US |
Prancis (Prancis) | fr-FR |
Hindi (India) | hi-IN |
Portugis (Brasil) | pt-BR |
Arab (Umum) | ar-XA |
Spanyol (Spanyol) | es-ES |
Prancis (Kanada) | fr-CA |
Indonesia (Indonesia) | id-ID |
Italia (Italia) | it-IT |
Jepang (Jepang) | ja-JP |
Turki (Turki) | tr-TR |
Vietnam (Vietnam) | vi-VN |
Bengali (India) | bn-IN |
Gujarati (India) | gu-IN |
Kannada (India) | kn-IN |
Malayalam (India) | ml-IN |
Marathi (India) | mr-IN |
Tamil (India) | ta-IN |
Telugu (India) | te-IN |
Belanda (Belanda) | nl-NL |
Korea (Korea Selatan) | ko-KR |
Mandarin (China) | cmn-CN |
Polandia (Polandia) | pl-PL |
Rusia (Rusia) | ru-RU |
Thai (Thailand) | th-TH |
Integrasi pihak ketiga
Untuk deployment aplikasi web dan seluler, Anda dapat menjelajahi opsi dari:
Langkah berikutnya
- Coba Live API di Google AI Studio.
- Untuk mengetahui info selengkapnya tentang Gemini 2.0 Flash Live, lihat halaman model.
- Coba contoh lainnya di cookbook Live API, cookbook Alat Live API, dan skrip Memulai Live API.