Multimodal Live API

Multimodal Live API memungkinkan interaksi dua arah dengan latensi rendah yang menggunakan input teks, audio, dan video, dengan output audio dan teks. Hal ini memfasilitasi percakapan suara yang alami dan mirip manusia dengan kemampuan untuk mengganggu model kapan saja. Kemampuan pemahaman video model memperluas modalitas komunikasi, sehingga Anda dapat membagikan input kamera atau screencast dan mengajukan pertanyaan tentangnya.

Kemampuan

Multimodal Live API mencakup kemampuan utama berikut:

  • Multimodalitas: Model dapat melihat, mendengar, dan berbicara.
  • Interaksi real-time latensi rendah: Model dapat 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: Anda dapat mengintegrasikan model dengan layanan dan sumber data eksternal.

Multimodal Live API dirancang untuk komunikasi server ke server.

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

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

Menetapkan variabel lingkungan

Untuk menetapkan nilai yang sesuai dan mengekspor variabel:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=YOUR_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

Mengirim dan menerima SMS

client = genai.Client()
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async with client.aio.live.connect(model=model_id, config=config) as session:
    message = "Hello? Gemini, are you there?"
    print("> ", message, "\n")
    await session.send(message, end_of_turn=True)

    async for response in session.receive():
        print(response.text)

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 atau membuat/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.

Anda menentukan fungsi menggunakan JSON, khususnya dengan subset tertentu dari format skema OpenAPI. Satu deklarasi fungsi dapat menyertakan parameter berikut:

  • name (string): ID unik untuk fungsi dalam panggilan API.
  • description (string): Penjelasan lengkap tentang tujuan dan kemampuan fungsi.
  • parameters (objek): Menentukan data input yang diperlukan oleh fungsi.
    • type (string): Menentukan jenis data secara keseluruhan, seperti objek.
    • properties (objek): Mencantumkan setiap parameter, masing-masing dengan:
    • type (string): Jenis data parameter, seperti string, bilangan bulat, boolean.
    • description (string): Penjelasan yang jelas tentang tujuan parameter dan format yang diharapkan.
    • required (array): Array string yang mencantumkan nama parameter yang wajib agar fungsi dapat beroperasi.

Untuk contoh kode deklarasi fungsi menggunakan perintah cURL, lihat Pengantar pemanggilan fungsi dengan Gemini API. Untuk contoh cara membuat deklarasi fungsi menggunakan Gemini API SDK, lihat Tutorial panggilan fungsi.

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.

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.

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

  • Puck
  • Charon
  • Kore
  • Fenrir
  • Aoede

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": VOICE_NAME
    }
  }
}

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 saat ini tidak dapat dikonfigurasi.

Batasan tambahan

Endpoint manual tidak didukung.

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

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, hal ini berbeda dengan ClientContentUpdate:

  • Dapat dikirim secara terus-menerus tanpa gangguan pada pembuatan model.
  • Jika perlu menggabungkan data yang diselingi di seluruh ClientContentUpdate dan RealtimeUpdate, 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).
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 berhenti dan mengosongkan antrean 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 menentukan sumber yang digunakan untuk mendasarkan 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 yang sepenuhnya memenuhi syarat dari endpoint model penayang atau model yang disesuaikan yang akan digunakan.

Format model penayang: projects/{project}/locations/{location}/publishers/*/models/*
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.

Langkah selanjutnya