Multimodal Live API memungkinkan interaksi suara dan video dua arah dengan latensi rendah dengan Gemini. Dengan Multimodal Live API, Anda dapat memberikan pengalaman percakapan suara yang alami dan seperti manusia kepada pengguna akhir, serta kemampuan untuk mengganggu respons model menggunakan perintah suara. Model ini dapat memproses input teks, audio, dan video, serta dapat memberikan output teks dan audio.
Anda dapat mencoba Multimodal Live API di Google AI Studio.
Menggunakan Multimodal Live API
Bagian ini menjelaskan cara menggunakan Multimodal Live API dengan salah satu SDK kami. Untuk informasi selengkapnya tentang WebSockets API yang mendasarinya, lihat referensi WebSockets API di bawah.
Mengirim dan menerima teks
import asyncio
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"
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(input=message, end_of_turn=True)
async for response in session.receive():
if response.text is not None:
print(response.text, end="")
if __name__ == "__main__":
asyncio.run(main())
Menerima audio
Contoh berikut menunjukkan cara menerima data audio dan menulisnya ke file .wav
.
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-exp"
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(input=message, end_of_turn=True)
async for idx,response in async_enumerate(session.receive()):
if response.data is not None:
wf.writeframes(response.data)
# Comment this out 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())
Format audio
Multimodal Live API mendukung format audio berikut:
- Format audio input: Audio PCM mentah 16 bit pada 16 kHz little-endian
- Format audio output: Audio PCM 16 bit mentah pada 24 kHz little-endian
Melakukan 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:
from google.genai import types
turns = [
types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))
turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))
{
"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
Multimodal Live API mendukung suara berikut: Aoede, Charon, Fenrir, Kore, dan Puck.
Untuk menentukan suara, tetapkan nama suara dalam objek speechConfig
sebagai bagian
dari konfigurasi sesi:
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")
)
)
)
{
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
Menggunakan panggilan fungsi
Anda dapat menentukan alat dengan Multimodal Live API. Lihat Tutorial panggilan fungsi untuk mempelajari panggilan fungsi lebih lanjut.
Alat harus ditentukan sebagai bagian dari konfigurasi sesi:
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(input="Turn the lights down to a romantic level", end_of_turn=True)
async for response in session.receive():
print(response.tool_call)
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. Eksekusi dijeda hingga hasil setiap panggilan fungsi tersedia, yang memastikan pemrosesan berurutan.
Klien harus merespons dengan BidiGenerateContentToolResponse.
Input audio dan output audio berdampak negatif pada kemampuan model untuk menggunakan panggilan fungsi.
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 not None:
# The generation was interrupted
Batasan
Pertimbangkan batasan Multimodal Live API dan Gemini 2.0 berikut saat Anda merencanakan project.
Autentikasi klien
Multimodal 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 Multimodal Live API.
Histori percakapan
Meskipun model melacak interaksi dalam sesi, histori percakapan tidak disimpan. Saat sesi berakhir, konteks yang sesuai akan dihapus.
Untuk memulihkan sesi sebelumnya atau memberi model konteks historis interaksi pengguna, aplikasi harus mempertahankan log percakapannya sendiri dan menggunakan pesan BidiGenerateContentClientContent untuk mengirim informasi ini di awal sesi baru.
Durasi sesi maksimum
Durasi sesi dibatasi hingga 15 menit untuk audio atau hingga 2 menit audio dan video. Jika durasi sesi melebihi batas, koneksi akan dihentikan.
Model juga dibatasi oleh ukuran konteks. Mengirim potongan konten yang besar bersama dengan streaming video dan audio dapat menyebabkan penghentian sesi lebih awal.
Deteksi aktivitas suara (VAD)
Model ini secara otomatis melakukan deteksi aktivitas suara (VAD) pada streaming input audio yang berkelanjutan. VAD selalu diaktifkan, dan parameternya tidak dapat dikonfigurasi.
Jumlah token
Jumlah token tidak didukung.
Batas kapasitas
Batas kapasitas berikut berlaku:
- 3 sesi serentak per kunci API
- 4 juta token per menit
Referensi WebSockets API
Multimodal Live API adalah API stateful yang menggunakan WebSockets. Di bagian ini, Anda akan menemukan detail tambahan terkait WebSockets API.
Sesi
Koneksi WebSocket membuat sesi antara klien dan server Gemini. Setelah klien memulai koneksi baru, sesi dapat bertukar pesan dengan server untuk:
- Mengirim teks, audio, atau video ke server Gemini.
- Menerima permintaan panggilan audio, teks, atau fungsi dari server Gemini.
Pesan awal setelah koneksi menetapkan konfigurasi sesi, yang mencakup model, parameter pembuatan, petunjuk sistem, dan alat.
Lihat contoh konfigurasi berikut. Perhatikan bahwa casing nama di SDK dapat bervariasi. Anda dapat mencari opsi konfigurasi Python SDK di sini.
{
"model": string,
"generationConfig": {
"candidateCount": integer,
"maxOutputTokens": integer,
"temperature": number,
"topP": number,
"topK": integer,
"presencePenalty": number,
"frequencyPenalty": number,
"responseModalities": [string],
"speechConfig": object
},
"systemInstruction": string,
"tools": [object]
}
Mengirim pesan
Untuk bertukar pesan melalui koneksi WebSocket, klien harus mengirim objek JSON melalui koneksi WebSocket yang terbuka. Objek JSON harus memiliki tepat satu kolom dari kumpulan objek berikut:
{
"setup": BidiGenerateContentSetup,
"clientContent": BidiGenerateContentClientContent,
"realtimeInput": BidiGenerateContentRealtimeInput,
"toolResponse": BidiGenerateContentToolResponse
}
Pesan klien yang didukung
Lihat pesan klien yang didukung dalam tabel berikut:
Pesan | Deskripsi |
---|---|
BidiGenerateContentSetup |
Konfigurasi sesi yang akan dikirim dalam pesan pertama |
BidiGenerateContentClientContent |
Pembaruan konten inkremental dari percakapan saat ini yang dikirim dari klien |
BidiGenerateContentRealtimeInput |
Input audio atau video real-time |
BidiGenerateContentToolResponse |
Respons terhadap ToolCallMessage yang diterima dari server |
Menerima pesan
Untuk menerima pesan dari Gemini, dengarkan peristiwa 'pesan' WebSocket, lalu uraikan hasilnya sesuai dengan definisi pesan server yang didukung.
Lihat referensi berikut:
async with client.aio.live.connect(model='...', config=config) as session:
await session.send(input='Hello world!', end_of_turn=True)
async for message in session.receive():
print(message)
Pesan server akan memiliki tepat satu kolom dari kumpulan objek berikut:
{
"setupComplete": BidiGenerateContentSetupComplete,
"serverContent": BidiGenerateContentServerContent,
"toolCall": BidiGenerateContentToolCall,
"toolCallCancellation": BidiGenerateContentToolCallCancellation
}
Pesan server yang didukung
Lihat pesan server yang didukung dalam tabel berikut:
Pesan | Deskripsi |
---|---|
BidiGenerateContentSetupComplete |
Pesan BidiGenerateContentSetup dari klien, yang dikirim saat penyiapan selesai |
BidiGenerateContentServerContent |
Konten yang dihasilkan oleh model sebagai respons terhadap pesan klien |
BidiGenerateContentToolCall |
Minta klien untuk menjalankan panggilan fungsi dan menampilkan respons dengan ID yang cocok |
BidiGenerateContentToolCallCancellation |
Dikirim saat panggilan fungsi dibatalkan karena pengguna mengganggu output model |
Pesan dan peristiwa
BidiGenerateContentClientContent
Pembaruan inkremental dari percakapan saat ini yang dikirim dari klien. Semua konten di sini ditambahkan tanpa syarat ke histori percakapan dan digunakan sebagai bagian dari perintah ke model untuk membuat konten.
Pesan di sini akan mengganggu pembuatan model saat ini.
Kolom | |
---|---|
turns[] |
Opsional. Konten yang ditambahkan ke percakapan saat ini dengan model. Untuk kueri satu giliran, ini adalah satu instance. Untuk kueri multi-giliran, ini adalah kolom berulang yang berisi histori percakapan dan permintaan terbaru. |
turn_ |
Opsional. Jika benar, menunjukkan bahwa pembuatan konten server harus dimulai dengan perintah yang saat ini diakumulasikan. Jika tidak, server akan menunggu pesan tambahan sebelum memulai pembuatan. |
BidiGenerateContentRealtimeInput
Input pengguna yang dikirim secara real time.
Dalam beberapa hal, hal ini berbeda dengan BidiGenerateContentClientContent
:
- Dapat dikirim secara terus-menerus tanpa gangguan pada pembuatan model.
- Jika perlu mencampur data yang diselingi di seluruh
BidiGenerateContentClientContent
danBidiGenerateContentRealtimeInput
, server akan mencoba mengoptimalkan respons terbaik, tetapi tidak ada jaminan. - Akhir giliran tidak ditentukan secara eksplisit, tetapi berasal dari aktivitas pengguna (misalnya, akhir ucapan).
- Bahkan sebelum akhir giliran, data diproses secara bertahap untuk mengoptimalkan awal respons yang cepat dari model.
- Selalu diasumsikan sebagai input pengguna (tidak dapat digunakan untuk mengisi histori percakapan). Dapat dikirim secara terus-menerus tanpa gangguan. Model ini otomatis mendeteksi awal dan akhir ucapan pengguna, lalu memulai atau menghentikan streaming respons yang sesuai. Data diproses secara bertahap saat tiba, sehingga meminimalkan latensi.
Kolom | |
---|---|
media_ |
Opsional. Data byte yang disisipkan untuk input media. |
BidiGenerateContentServerContent
Update server inkremental yang dihasilkan oleh model sebagai respons terhadap pesan klien.
Konten dibuat secepat mungkin, dan bukan secara real time. Klien dapat memilih untuk melakukan buffering dan memutarnya secara real time.
Kolom | |
---|---|
turn_ |
Hanya output. Jika true, menunjukkan bahwa model telah selesai dibuat. Pembuatan hanya akan dimulai sebagai respons terhadap pesan klien tambahan. Dapat ditetapkan bersama |
interrupted |
Hanya output. Jika benar, menunjukkan bahwa pesan klien telah mengganggu pembuatan model saat ini. Jika klien memutar konten secara real time, ini adalah sinyal yang baik untuk menghentikan dan mengosongkan antrean pemutaran saat ini. |
grounding_ |
Hanya output. Metadata dasar untuk konten yang dihasilkan. |
model_ |
Hanya output. Konten yang telah dibuat model sebagai bagian dari percakapan saat ini dengan pengguna. |
BidiGenerateContentSetup
Pesan yang akan dikirim dalam pesan klien pertama dan satu-satunya. Berisi konfigurasi yang akan berlaku selama durasi sesi streaming.
Klien harus menunggu pesan BidiGenerateContentSetupComplete
sebelum mengirim pesan tambahan.
Kolom | |
---|---|
model |
Wajib. Nama resource model. ID ini berfungsi sebagai ID yang akan digunakan Model. Format: |
generation_ |
Opsional. Konfigurasi pembuatan. Kolom berikut tidak didukung:
|
system_ |
Opsional. Pengguna memberikan petunjuk sistem untuk model. Catatan: Hanya teks yang boleh digunakan dalam bagian. Konten di setiap bagian akan berada dalam paragraf terpisah. |
tools[] |
Opsional. Daftar
|
BidiGenerateContentSetupComplete
Jenis ini tidak memiliki kolom.
Dikirim sebagai respons terhadap pesan BidiGenerateContentSetup
dari klien.
BidiGenerateContentToolCall
Minta klien untuk mengeksekusi panggilan fungsi dan menampilkan respons dengan id
yang cocok.
Kolom | |
---|---|
function_ |
Hanya output. Panggilan fungsi yang akan dieksekusi. |
BidiGenerateContentToolCallCancellation
Notifikasi untuk klien bahwa ToolCallMessage
yang dikeluarkan sebelumnya dengan id
yang ditentukan seharusnya tidak dieksekusi dan harus dibatalkan. Jika ada efek samping pada panggilan alat tersebut, klien dapat mencoba mengurungkan panggilan alat. Pesan ini hanya terjadi jika klien mengganggu giliran server.
Kolom | |
---|---|
ids[] |
Hanya output. ID panggilan alat yang akan dibatalkan. |
BidiGenerateContentToolResponse
Respons yang dibuat klien untuk ToolCall
yang diterima dari server. Setiap objek FunctionResponse
dicocokkan dengan objek FunctionCall
masing-masing oleh kolom id
.
Perhatikan bahwa dalam panggilan fungsi GenerateContent API streaming server dan unary terjadi dengan bertukar bagian Content
, sedangkan dalam panggilan fungsi GenerateContent API bidi terjadi melalui kumpulan pesan khusus ini.
Kolom | |
---|---|
function_ |
Opsional. Respons terhadap panggilan fungsi. |
Informasi selengkapnya tentang jenis umum
Untuk informasi selengkapnya tentang jenis resource API yang umum digunakan Blob
,
Content
, FunctionCall
, FunctionResponse
, GenerationConfig
,
GroundingMetadata
, dan Tool
, lihat
Membuat konten.
Integrasi pihak ketiga
Untuk deployment aplikasi web dan seluler, Anda dapat menjelajahi opsi dari: