Referensi Live API

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

Untuk mengetahui informasi selengkapnya tentang Live API, lihat Live API.

Kemampuan

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 kembali informasi yang sebelumnya didengar atau dilihat.
• Dukungan untuk panggilan fungsi, eksekusi kode, dan Penelusuran sebagai Alat: Anda dapat mengintegrasikan model dengan layanan dan sumber data eksternal.

Live API dirancang untuk komunikasi server ke server.

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

Model yang didukung

• Gemini 2.5 Flash dengan audio native Live API
  previewPratinjau
• Gemini 2.0 Flash dengan Live API
  previewPratinjau
• Gemini 2.5 Flash

Mulai

Untuk mencoba Live API, buka Vertex AI Studio, lalu klik Start Session.

Live API adalah API stateful yang menggunakan WebSockets.

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

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    HttpOptions,
    Modality,
    Part,
)

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-live-preview-04-09"

async with client.aio.live.connect(
    model=model_id,
    config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
) as session:
    text_input = "Hello? Gemini, are you there?"
    print("> ", text_input, "\n")
    await session.send_client_content(turns=Content(role="user", parts=[Part(text=text_input)]))

    response = []

    async for message in session.receive():
        if message.text:
            response.append(message.text)

    print("".join(response))
# Example output:
# >  Hello? Gemini, are you there?
# Yes, I'm here. What would you like to talk about?

Panduan integrasi

Bagian ini menjelaskan cara kerja integrasi dengan Live 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 audio, teks, atau panggilan 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,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

Untuk mengetahui informasi selengkapnya, lihat BidiGenerateContentSetup.

Mengirim pesan

Pesan adalah objek berformat JSON yang dipertukarkan melalui koneksi WebSocket.

Untuk mengirim pesan, 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:

Menerima pesan

Untuk menerima pesan dari Gemini, dengarkan peristiwa 'message' WebSocket, lalu parsing 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 akan memiliki tepat satu kolom dari set objek berikut:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
  "usageMetadata": UsageMetadata
  "goAway": GoAway
  "sessionResumptionUpdate": SessionResumptionUpdate
  "inputTranscription": BidiGenerateContentTranscription
  "outputTranscription": BidiGenerateContentTranscription
}

Pesan server yang didukung

Lihat pesan server yang didukung dalam tabel berikut:

Update konten inkremental

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

Lihat contoh pesan konteks berikut:

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

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

Streaming audio dan video

Eksekusi kode

Untuk mempelajari lebih lanjut eksekusi kode, lihat Eksekusi kode.

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 pilihan dari format skema OpenAPI. Deklarasi fungsi tunggal dapat mencakup 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 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 dan format yang diharapkan dari parameter.

  • required (array): Array string yang mencantumkan nama parameter yang wajib ada agar fungsi dapat beroperasi.

Untuk contoh kode deklarasi fungsi menggunakan perintah curl, lihat Pemanggilan fungsi dengan Gemini API. Untuk contoh cara membuat deklarasi fungsi menggunakan SDK Gemini API, lihat tutorial Panggilan fungsi.

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

Klien harus merespons dengan BidiGenerateContentToolResponse.

Untuk mempelajari lebih lanjut, lihat Pengantar panggilan fungsi.

Format audio

Lihat daftar format audio yang didukung.

Petunjuk sistem

Anda dapat memberikan petunjuk sistem untuk mengontrol output model dengan lebih baik dan menentukan nada serta 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 update konten inkremental.

Gangguan

Pengguna dapat menghentikan output model kapan saja. Saat Deteksi aktivitas suara (VAD) mendeteksi gangguan, pembuatan yang sedang berlangsung dibatalkan dan dibuang. Hanya informasi yang sudah dikirim ke klien yang dipertahankan dalam histori sesi. Server kemudian mengirim pesan BidiGenerateContentServerContent untuk melaporkan gangguan.

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

Suara

Untuk menentukan suara, tetapkan voiceName dalam objek speechConfig, sebagai bagian dari konfigurasi sesi.

Lihat representasi JSON objek speechConfig berikut:

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

Untuk melihat daftar suara yang didukung, lihat Mengubah setelan suara dan bahasa.

Batasan

Pertimbangkan batasan Live API dan Gemini 2.0 berikut saat Anda merencanakan project.

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 yang aman dengan Live API.

Durasi sesi maksimum

Durasi maksimum default sesi percakapan adalah 10 menit. Untuk mengetahui informasi selengkapnya, lihat Durasi sesi.

Deteksi aktivitas suara (VAD)

Secara default, model akan otomatis melakukan deteksi aktivitas suara (VAD) pada aliran input audio berkelanjutan. VAD dapat dikonfigurasi dengan kolom RealtimeInputConfig.AutomaticActivityDetection dari pesan penyiapan.

Saat aliran audio dijeda selama lebih dari satu detik (misalnya, saat pengguna menonaktifkan mikrofon), peristiwa AudioStreamEnd dikirim untuk menghapus semua audio yang di-cache. Klien dapat melanjutkan pengiriman data audio kapan saja.

Atau, VAD otomatis dapat dinonaktifkan dengan menyetel 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 pada streaming ditandai dengan pesan ActivityEnd.

Batasan tambahan

Pengakhiran titik akhir 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 frekuensi berikut berlaku:

• 5.000 sesi serentak per kunci API
• 4 juta token per menit

Pesan dan acara

Langkah berikutnya

• Pelajari lebih lanjut pemanggilan fungsi.
• Lihat Referensi pemanggilan fungsi untuk melihat contohnya.