Multimodal Live API

Multimodal Live API memungkinkan interaksi suara dan video dua arah dengan latensi rendah dengan Gemini. Dengan menggunakan Multimodal Live API, Anda dapat memberikan pengalaman percakapan suara alami yang mirip manusia kepada pengguna akhir, dan dengan kemampuan untuk mengganggu respons model menggunakan perintah suara. Model ini dapat memproses input teks, audio, dan video, serta dapat memberikan output teks dan audio.

Kemampuan

Multimodal Live API mencakup kemampuan utama berikut:

  • Multimodalitas: Model dapat melihat, mendengar, dan berbicara.
  • Interaksi real-time latensi rendah: Memberikan respons yang cepat.
  • Memori sesi: Model mempertahankan memori semua interaksi dalam satu sesi, mengingat informasi yang didengar atau dilihat sebelumnya.
  • Dukungan untuk panggilan fungsi, eksekusi kode, dan Penelusuran sebagai alat: Memungkinkan integrasi dengan layanan dan sumber data eksternal.
  • Deteksi aktivitas suara otomatis (VAD): Model ini dapat mengenali dengan akurat saat pengguna mulai dan berhenti berbicara. Hal ini memungkinkan interaksi percakapan yang alami dan memungkinkan pengguna untuk mengganggu model kapan saja.

Anda dapat mencoba Multimodal Live API di Google AI Studio.

Mulai

Multimodal Live API adalah API stateful yang menggunakan WebSockets.

Bagian ini menunjukkan contoh cara menggunakan Multimodal Live API untuk pembuatan teks ke teks, menggunakan Python 3.9+.

Menginstal library Gemini API

Untuk menginstal paket google-genai, gunakan perintah pip berikut:

!pip3 install google-genai

Mengimpor dependensi

Untuk mengimpor dependensi:

from google import genai

Mengirim dan menerima SMS

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

            async for response in session.receive():
                if response.text is None:
                    continue
                print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Panduan integrasi

Bagian ini menjelaskan cara kerja integrasi dengan Multimodal Live API.

Sesi

Sesi mewakili satu koneksi WebSocket 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 respons panggilan audio, teks, atau fungsi dari server Gemini.

Konfigurasi sesi dikirim dalam pesan pertama setelah koneksi. Konfigurasi sesi mencakup model, parameter pembuatan, petunjuk sistem, dan alat.

Lihat contoh konfigurasi berikut:

{​​
  "model": string,
  "generation_config": {​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

Untuk informasi selengkapnya, lihat BidiGenerateContentSetup.

Mengirim pesan

Pesan adalah string berformat JSON yang dipertukarkan melalui koneksi WebSocket.

Untuk mengirim pesan, klien harus mengirim pesan klien yang didukung dalam string berformat JSON dengan salah satu koneksi WebSocket terbuka.

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:

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

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

Update konten inkremental

Gunakan update inkremental untuk mengirim input teks, membuat, atau memulihkan konteks sesi. Untuk konteks singkat, Anda dapat mengirim interaksi belokan demi belokan untuk mewakili urutan peristiwa yang tepat. Untuk konteks yang lebih panjang, sebaiknya berikan satu ringkasan pesan untuk mengosongkan jendela konteks untuk interaksi lanjutan.

Lihat contoh pesan konteks berikut:

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

Perhatikan bahwa meskipun bagian konten dapat berupa jenis functionResponse, BidiGenerateContentClientContent tidak boleh digunakan untuk memberikan respons ke panggilan fungsi yang dikeluarkan oleh model. BidiGenerateContentToolResponse harus digunakan sebagai gantinya. BidiGenerateContentClientContent hanya boleh digunakan untuk menetapkan konteks sebelumnya atau memberikan input teks ke percakapan.

Streaming audio dan video

Panggilan fungsi

Semua fungsi harus dideklarasikan di awal sesi dengan mengirimkan definisi alat sebagai bagian dari pesan BidiGenerateContentSetup.

Lihat Tutorial panggilan fungsi untuk mempelajari panggilan fungsi lebih lanjut.

Dari satu perintah, model dapat menghasilkan beberapa panggilan fungsi dan kode yang diperlukan untuk merantai outputnya. Kode ini dijalankan di lingkungan sandbox, yang menghasilkan pesan BidiGenerateContentToolCall berikutnya. Eksekusi dijeda hingga hasil setiap panggilan fungsi tersedia, yang memastikan pemrosesan berurutan.

Klien akan merespons dengan BidiGenerateContentToolResponse.

Input audio dan output audio berdampak negatif pada kemampuan model untuk menggunakan panggilan fungsi.

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

Petunjuk sistem

Anda dapat memberikan petunjuk sistem untuk mengontrol output model dengan lebih baik dan menentukan nada dan sentimen respons audio.

Petunjuk sistem ditambahkan ke perintah sebelum interaksi dimulai dan tetap berlaku selama seluruh sesi.

Petunjuk sistem hanya dapat ditetapkan di awal sesi, segera setelah koneksi awal. Untuk memberikan input lebih lanjut ke model selama sesi, gunakan pembaruan konten inkremental.

Interupsi

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 mengirim pesan BidiGenerateContentServerContent untuk melaporkan gangguan.

Selain itu, server Gemini akan menghapus panggilan fungsi yang tertunda dan mengirim pesan BidiGenerateContentServerContent dengan ID panggilan yang dibatalkan.

Suara

Multimodal Live API mendukung suara berikut: Aoede, Charon, Fenrir, Kore, dan Puck.

Untuk menentukan suara, tetapkan voice_name dalam objek speech_config, sebagai bagian dari konfigurasi sesi Anda.

Lihat representasi JSON objek speech_config berikut:

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

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.

Untuk aplikasi web dan seluler, sebaiknya gunakan integrasi dari partner kami di Daily.

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

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, 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 merupakan input langsung pengguna yang dikirim secara real time. 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:

  • response_logprobs
  • response_mime_type
  • logprobs
  • response_schema
  • stop_sequence
  • routing_config
  • audio_timestamp
system_instruction

Content

Opsional. Pengguna memberikan petunjuk sistem untuk model.

Catatan: Hanya teks yang boleh digunakan dalam bagian dan 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 menjalankan function_calls 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.