Multimodal Live API

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:

PythonJSON
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:

PythonJSON
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[]

Content

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_complete

bool

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 dan BidiGenerateContentRealtimeInput, 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_chunks[]

Blob

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_complete

bool

Hanya output. Jika true, menunjukkan bahwa model telah selesai dibuat. Pembuatan hanya akan dimulai sebagai respons terhadap pesan klien tambahan. Dapat ditetapkan bersama content, yang menunjukkan bahwa content adalah yang terakhir dalam giliran.

interrupted

bool

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_metadata

GroundingMetadata

Hanya output. Metadata dasar untuk konten yang dihasilkan.

model_turn

Content

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

string

Wajib. Nama resource model. ID ini berfungsi sebagai ID yang akan digunakan Model.

Format: models/{model}

generation_config

GenerationConfig

Opsional. Konfigurasi pembuatan.

Kolom berikut tidak didukung:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_instruction

Content

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[]

Tool

Opsional. Daftar Tools yang dapat digunakan model untuk menghasilkan respons berikutnya.

Tool adalah potongan kode yang memungkinkan sistem berinteraksi dengan sistem eksternal untuk melakukan tindakan, atau serangkaian tindakan, di luar pengetahuan dan cakupan model.

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_calls[]

FunctionCall

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[]

string

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_responses[]

FunctionResponse

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: