Referensi Live API

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Live API memungkinkan interaksi suara dan video dua arah dengan latensi rendah dengan Gemini. Dengan menggunakan Live API, Anda dapat memberikan pengalaman percakapan suara alami dan seperti manusia kepada pengguna akhir, serta kemampuan untuk menyela respons model menggunakan perintah suara. Live API dapat memproses input teks, audio, dan video, serta dapat 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 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.

Live API dirancang untuk komunikasi server ke server.

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

Model yang didukung

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 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,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

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

Untuk 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 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 mengurai 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 kumpulan 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, menetapkan konteks sesi, atau memulihkan konteks sesi. Untuk konteks singkat, Anda dapat mengirim interaksi per belokan untuk mewakili urutan peristiwa yang tepat. Untuk konteks yang lebih panjang, sebaiknya berikan ringkasan pesan tunggal untuk mengosongkan jendela konteks untuk 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 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

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

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

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

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

Durasi sesi maksimum

Durasi maksimum sesi percakapan default 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 streaming input audio yang berkelanjutan. VAD dapat dikonfigurasi dengan kolom RealtimeInputConfig.AutomaticActivityDetection dari pesan penyiapan.

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

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

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

Langkah berikutnya

• Pelajari lebih lanjut panggilan fungsi.
• Lihat Referensi panggilan fungsi untuk mengetahui contohnya.