Panduan kemampuan Live API

Ini adalah panduan komprehensif yang mencakup kemampuan dan konfigurasi yang tersedia dengan Live API. Lihat halaman Mulai menggunakan Live API untuk mengetahui ringkasan dan kode contoh untuk kasus penggunaan umum.

Sebelum memulai

  • Pahami konsep inti: Jika belum melakukannya, baca halaman Mulai menggunakan Live API terlebih dahulu. Bagian ini akan memperkenalkan prinsip-prinsip dasar Live API, cara kerjanya, dan berbagai pendekatan penerapan.
  • Coba Live API di AI Studio: Anda mungkin merasa berguna untuk mencoba Live API di Google AI Studio sebelum mulai membangun. Untuk menggunakan Live API di Google AI Studio, pilih Stream.

Perbandingan model

Tabel berikut merangkum perbedaan utama antara model Pratinjau Langsung Gemini 3.1 Flash dan Pratinjau Langsung Gemini 2.5 Flash:

Fitur Pratinjau Langsung Gemini 3.1 Flash Pratinjau Langsung Gemini 2.5 Flash
Penalaran Menggunakan thinkingLevel untuk mengontrol kedalaman penalaran dengan setelan seperti minimal, low, medium, dan high. Defaultnya adalah minimal untuk mengoptimalkan latensi terendah. Lihat Tingkat dan anggaran yang perlu dipertimbangkan. Menggunakan thinkingBudget untuk menetapkan jumlah token penalaran. Pemikiran dinamis diaktifkan secara default. Tetapkan thinkingBudget ke 0 untuk menonaktifkan. Lihat Tingkat dan anggaran yang perlu dipertimbangkan.
Menerima respons Satu peristiwa server dapat berisi beberapa bagian konten secara bersamaan (misalnya, inlineData dan transkrip). Pastikan kode Anda memproses semua bagian dalam setiap peristiwa untuk menghindari hilangnya konten. Setiap peristiwa server hanya berisi satu bagian konten. Bagian dikirim dalam acara terpisah.
Konten klien send_client_content hanya didukung untuk mengisi histori konteks awal (memerlukan setelan initial_history_in_client_content dalam konfigurasi sesi). Untuk mengirim pembaruan teks selama percakapan, gunakan send_realtime_input. send_client_content didukung di seluruh percakapan untuk mengirim update konten inkremental dan menetapkan konteks.
Cakupan belokan Default-nya adalah TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO. Giliran model mencakup aktivitas audio yang terdeteksi dan semua frame video. Default-nya adalah TURN_INCLUDES_ONLY_ACTIVITY. Giliran model hanya mencakup aktivitas yang terdeteksi.
VAD Kustom (activity_start/activity_end) Didukung. Nonaktifkan VAD otomatis dan kirim pesan activityStart dan activityEnd secara manual untuk mengontrol batas giliran. Didukung. Nonaktifkan VAD otomatis dan kirim pesan activityStart dan activityEnd secara manual untuk mengontrol batas giliran.
Konfigurasi VAD otomatis Didukung. Konfigurasi parameter seperti start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms, dan silence_duration_ms. Didukung. Konfigurasi parameter seperti start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms, dan silence_duration_ms.
Panggilan fungsi asinkron (behavior: NON_BLOCKING) Tidak didukung. Panggilan fungsi hanya berurutan. Model tidak akan mulai merespons hingga Anda mengirimkan respons alat. Didukung. Tetapkan behavior ke NON_BLOCKING pada deklarasi fungsi agar model dapat terus berinteraksi saat fungsi berjalan. Kontrol cara model menangani respons dengan parameter scheduling (INTERRUPT, WHEN_IDLE, atau SILENT).
Audio proaktif Tidak didukung Didukung. Jika diaktifkan, model dapat secara proaktif memutuskan untuk tidak merespons jika konten input tidak relevan. Tetapkan proactive_audio ke true di konfigurasi proactivity (memerlukan v1beta).
Dialog afektif Tidak didukung Didukung. Model menyesuaikan gaya responsnya agar sesuai dengan ekspresi dan intonasi input. Tetapkan enable_affective_dialog ke true di konfigurasi sesi (memerlukan v1beta).

Untuk bermigrasi dari Gemini 2.5 Flash Live ke Gemini 3.1 Flash Live, lihat panduan migrasi.

Membuat koneksi

Contoh berikut menunjukkan cara membuat koneksi dengan kunci API:

Python

import asyncio
from google import genai

client = genai.Client()

model = "gemini-3.1-flash-live-preview"
config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started")
        # Send content...

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        console.debug(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  console.debug("Session started");
  // Send content...

  session.close();
}

main();

Modalitas interaksi

Bagian berikut memberikan contoh dan konteks pendukung untuk berbagai modalitas input dan output yang tersedia di Live API.

Mengirim audio

Audio harus dikirim sebagai data PCM mentah (audio PCM 16-bit mentah, 16 kHz, little-endian).

Python

# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)

JavaScript

// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});

Format audio

Data audio di Live API selalu berupa PCM 16-bit mentah, little-endian. Output audio selalu menggunakan frekuensi sampling 24 kHz. Audio input secara native adalah 16 kHz, tetapi Live API akan melakukan pengambilan sampel ulang jika diperlukan sehingga frekuensi sampel apa pun dapat dikirim. Untuk menyampaikan sample rate audio input, tetapkan jenis MIME setiap Blob yang berisi audio ke nilai seperti audio/pcm;rate=16000.

Menerima audio

Respons audio model diterima sebagai potongan data.

Python

async for response in session.receive():
    if response.server_content and response.server_content.model_turn:
        for part in response.server_content.model_turn.parts:
            if part.inline_data:
                audio_data = part.inline_data.data
                # Process or play the audio data

JavaScript

// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data;
      // Process or play audioData (base64 encoded string)
    }
  }
}

Mengirim SMS

Teks dapat dikirim menggunakan send_realtime_input (Python) atau sendRealtimeInput (JavaScript).

Python

await session.send_realtime_input(text="Hello, how are you?")

JavaScript

session.sendRealtimeInput({
  text: 'Hello, how are you?'
});

Mengirim video

Frame video dikirim sebagai gambar individual (misalnya, JPEG atau PNG) pada kecepatan frame tertentu (maks. 1 frame per detik).

Python

# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
    video=types.Blob(
        data=frame,
        mime_type="image/jpeg"
    )
)

JavaScript

// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
  video: {
    data: frame.toString('base64'),
    mimeType: 'image/jpeg'
  }
});

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:

Python

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)

JavaScript

let inputTurns = [
  { "role": "user", "parts": [{ "text": "What is the capital of France?" }] },
  { "role": "model", "parts": [{ "text": "Paris" }] },
]

session.sendClientContent({ turns: inputTurns, turnComplete: false })

inputTurns = [{ "role": "user", "parts": [{ "text": "What is the capital of Germany?" }] }]

session.sendClientContent({ turns: inputTurns, turnComplete: true })

Untuk konteks yang lebih panjang, sebaiknya berikan ringkasan pesan tunggal untuk mengosongkan jendela konteks untuk interaksi berikutnya. Lihat Melanjutkan Sesi untuk metode lain dalam memuat konteks sesi.

Transkripsi audio

Selain respons model, Anda juga dapat menerima transkripsi output audio dan input audio.

Untuk mengaktifkan transkripsi output audio model, kirim output_audio_transcription dalam konfigurasi penyiapan. Bahasa transkripsi disimpulkan dari respons model.

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

config = {
    "response_modalities": ["AUDIO"],
    "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';

const config = {
  responseModalities: [Modality.AUDIO],
  outputAudioTranscription: {}
};

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'Hello how are you?';
  session.sendClientContent({ turns: inputTurns });

  const turns = await handleTurn();

  for (const turn of turns) {
    if (turn.serverContent && turn.serverContent.outputTranscription) {
      console.debug('Received output transcription: %s\n', turn.serverContent.outputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

Untuk mengaktifkan transkripsi input audio model, kirim input_audio_transcription dalam konfigurasi penyiapan.

Python

import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as