Panduan developer untuk Gemini 3.8 Live

Gemini 3.8 Live adalah model percakapan real-time yang dibuat untuk interaksi suara dan video dua arah latensi rendah serta sintesis live avatar tatap muka. Didesain untuk alur kerja percakapan berkelanjutan, 3.8 Live menyediakan dialog afektif yang diaktifkan secara default, pemfilteran audio proaktif, alat pemblokiran pembatalan otomatis, dan pengalihan multibahasa dinamis.

Dokumen ini membahas topik berikut:

• Cara 3.8 Live sesuai dengan keluarga model Gemini.
• Kemampuan utama di 3.8 Live.
• Integrasi dengan Google Gen AI SDK.
• Aturan dan konvensi API yang diperlukan.
• Migrasi dari model Gemini Live API sebelumnya.

Peran dalam keluarga Gemini

3.8 Live dirancang untuk interaksi streaming real-time. Model ini beroperasi di seluruh WebSocket dua arah, memproses ucapan, feed kamera live, dan siaran layar dengan latensi sub-detik saat menghasilkan audio 24 kHz dan avatar video 24 FPS yang disinkronkan.

Spesifikasi dan perbandingan model

Tabel berikut membandingkan spesifikasi antara 3.8 Live dan model Gemini Live API sebelumnya:

Kapan menggunakan Gemini 3.8 Live

Gunakan 3.8 Live dalam skenario berikut:

• Anda memerlukan latensi percakapan yang rendah, pergantian giliran yang alami, dan pemulihan yang cepat saat pengguna menyela (barge-in).
• Aplikasi Anda memanggil alat eksternal dan memerlukan eksekusi non-pemblokiran sehingga output audio terus berlanjut saat sistem backend memproses permintaan.
• Anda ingin merender avatar digital yang berbicara dengan animasi wajah dan lip-sync yang disinkronkan pada 24 FPS tanpa pipeline rendering eksternal.
• Pengguna Anda berkomunikasi dalam beberapa bahasa, sehingga memerlukan deteksi dan pengalihan bahasa di tengah streaming di seluruh bahasa yang didukung.
• Anda memerlukan bias kosakata khusus domain untuk terminologi teknis, SKU, atau nama merek.

Untuk mengetahui spesifikasi lengkap dan batas kuota, lihat halaman model 3.8 Live.

Kemampuan utama di Gemini 3.8 Live

3.8 Live memperkenalkan kemampuan berikut:

• Sintesis video Avatar Live 24 FPS: 3.8 Live menghasilkan streaming video MP4 24 FPS yang disinkronkan (response_modalities=["VIDEO"]) langsung dari output model. Ekspresi wajah dan gerakan bibir yang dihasilkan selaras dengan ucapan yang disintesis secara real time.

  Anda dapat menggunakan avatar stok bawaan atau memberikan gambar referensi kustom untuk membuat petugas digital, agen layanan pelanggan, tutor virtual, atau karakter interaktif. Untuk mengetahui detail penyiapan, lihat Mengonfigurasi avatar live.

• Dialog afektif dan audio proaktif yang diaktifkan secara default:

  • Dialog afektif: Diaktifkan secara default di 3.8 Live. Model ini memproses prosodi akustik, isyarat vokal, jeda, dan infleksi ucapan dalam input audio pengguna untuk menyesuaikan nada vokal dan kecepatan percakapan.
  • Audio proaktif: Diaktifkan secara default di 3.8 Live. Model ini memfilter suara bising di sekitar dan ucapan latar belakang, sehingga hanya menghasilkan respons audio saat ditujukan oleh pengguna.

• Pemanggilan fungsi pemblokiran asinkron dan pembatalan otomatis: 3.8 Live menyediakan perilaku pemanggilan alat yang dirancang untuk ucapan real-time:

  • Eksekusi asinkron non-pemblokiran: Saat model menghasilkan panggilan alat, sesi audio tetap aktif sehingga agen dapat melakukan streaming konfirmasi percakapan ("Izinkan saya mengambil detail akun Anda...") dan menangani input lanjutan saat aplikasi klien Anda memanggil API backend.
  • Panggilan pemblokiran pembatalan otomatis (behavior="BLOCKING"): Saat deklarasi fungsi menetapkan behavior="BLOCKING", pembuatan akan dijeda hingga respons alat tiba. Jika input pengguna baru tiba saat panggilan pemblokiran berjalan, server Gemini Live API akan membatalkan panggilan yang tertunda.
  • Penanganan penyelaan sopan: Pada model sebelumnya, menampilkan respons alat dengan scheduling="INTERRUPT" saat pengguna berbicara akan tumpang-tindih dengan audio pengguna. Di 3.8 Live, server menurunkan kualitas jadwal ke WHEN_IDLE saat ucapan pengguna aktif dan memutar respons setelah pengguna selesai berbicara.

• Pengalihan multibahasa dinamis dan kosakata kustom:

  • Dukungan multibahasa: Mendeteksi dan beralih antarbahasa yang didukung di tengah sesi tanpa memulai ulang atau mengonfigurasi ulang koneksi.
  • Bias kosakata kustom: Menerima kata kunci khusus domain, nama diri, istilah medis, dan kode produk di AudioTranscriptionConfig (melalui input_audio_transcription) menggunakan custom_vocabulary untuk meningkatkan akurasi transkripsi.

• Grounding visual multimodal dengan kontrol media_resolution: Menerima streaming video real-time (frame JPEG 1 FPS, resolusi yang direkomendasikan 768x768) dan memungkinkan Anda mengonfigurasi media_resolution (MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH) untuk menyeimbangkan penggunaan token per frame dan detail visual.

Panduan memulai

Sebelum memulai, lakukan autentikasi menggunakan Kredensial Default Aplikasi Cloud de Confiance by S3NS (ADC).

Dalam contoh kode berikut, ganti PROJECT_ID dengan project ID Anda Cloud de Confiance .

Menginstal SDK

Instal atau update Google Gen AI SDK dan dependensi audio:

pip install --upgrade google-genai websockets numpy

Memulai sesi dua arah dengan pemanggilan alat asinkron

Contoh berikut membuat sesi real-time dengan gemini-3.8-live, mengonfigurasi bias kosakata kustom, dan menjalankan panggilan fungsi asinkron non-pemblokiran:

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

PROJECT_ID = "PROJECT_ID"
LOCATION = "us-central1"
MODEL_ID = "gemini-3.8-live"

# Initialize the Gen AI client for enterprise.
client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

# Define a tool for asynchronous execution.
order_lookup_tool = types.FunctionDeclaration(
    name="lookup_order_status",
    description="Fetches real-time shipping status for a customer order ID.",
    parameters=types.Schema(
        type="OBJECT",
        properties={
            "order_id": types.Schema(
                type="STRING",
                description="The order ID, for example, ORD-8472",
            ),
        },
        required=["order_id"],
    ),
)

# Configure the live connection.
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    system_instruction=types.Content(
        parts=[
            types.Part.from_text(
                text=(
                    "You are an enterprise concierge. When you call a tool, "
                    "briefly acknowledge the request and tell the user what you're doing. "
                    "If a tool returns no results, inform the user before trying again. "
                    "Never issue more than two consecutive tool calls without speaking."
                )
            )
        ]
    ),
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Aoede")
        ),
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["ORD-8472", "Gemini Live", "Express Shipping"]
    ),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    tools=[types.Tool(function_declarations=[order_lookup_tool])],
)

async def handle_tool_call(session, function_call):
    """Executes backend calls asynchronously without blocking incoming audio."""
    order_id = function_call.args.get("order_id", "")
    await asyncio.sleep(2.0)  # Simulate backend API latency.

    if not order_id.startswith("ORD-"):
        result = {
            "status": "invalid_argument",
            "retryable": False,
            "message": f"Order ID '{order_id}' is invalid. Ask the user to verify.",
        }
    else:
        result = {
            "status": "ok",
            "retryable": False,
            "order_id": order_id,
            "shipping_status": "Out for delivery by 4:00 PM",
        }

    # Send tool response matching the call ID.
    await session.send_tool_response(
        function_responses=[
            types.FunctionResponse(
                id=function_call.id,
                name=function_call.name,
                response=result,
            )
        ]
    )

async def main():
    async with client.aio.live.connect(model=MODEL_ID, config=config) as session:
        print(f"Connected to {MODEL_ID}")

        # Send initial text or stream 16 kHz PCM audio chunks.
        await session.send_realtime_input(
            text="Hi! Can you check the status of order ORD-8472?"
        )

        async for message in session.receive():
            # Handle asynchronous tool calls.
            if message.tool_call:
                for call in message.tool_call.function_calls:
                    asyncio.create_task(handle_tool_call(session, call))

            # Process audio output chunks and transcriptions.
            if message.server_content:
                if (
                    message.server_content.output_transcription
                    and message.server_content.output_transcription.text
                ):
                    print(
                        f"Agent: {message.server_content.output_transcription.text}",
                        end="",
                        flush=True,
                    )

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

Aturan dan konvensi API yang diperlukan

Saat membangun dengan 3.8 Live, ikuti konvensi API berikut:

• Respons fungsi informatif: Jangan menampilkan kamus kosong ({}) atau None dari pengendali alat. Saat alat menampilkan error atau payload kosong, 3.8 Live mungkin menghasilkan panggilan fungsi berulang dengan argumen yang diubah kecuali jika respons menyertakan kolom status. Menampilkan kolom terstruktur di setiap respons alat:
  • status: String status yang dapat dibaca mesin, seperti "ok", "no_results", atau "invalid_argument".
  • retryable: Tetapkan ke false saat mengulangi panggilan akan menampilkan hasil yang sama.
  • message atau guidance: Teks yang menentukan status yang akan dilaporkan kepada pengguna.
• Batas percobaan ulang alat tingkat perintah: Sertakan batas percobaan ulang di system_instruction Anda. Misalnya: "Jika panggilan alat tidak menampilkan hasil, beri tahu pengguna, bukan menelusuri berulang kali dengan variasi parameter. Jangan pernah menjalankan lebih dari dua panggilan alat berturut-turut tanpa berbicara kepada pengguna."
• Pencocokan FunctionResponse yang ketat:
  • Setiap giliran FunctionResponse harus menyediakan id yang sama persis dari FunctionCall sebelumnya.
  • Teruskan objek respons langsung di FunctionResponse.response.
• Format audio streaming:
  • Audio input: PCM mono 16 kHz, 16-bit, little-endian (audio/pcm;rate=16000), yang di-streaming dalam potongan 20 md hingga 100 md.
  • Audio output: PCM mono 24 kHz.
• Parameter lama yang dihapus: Jangan meneruskan enable_affective_dialog atau proactivity dalam konfigurasi Anda; fitur ini diaktifkan secara default di 3.8 Live.
• Menyemai histori percakapan: Jika Anda menyemai histori multi-giliran menggunakan send_client_content, tunggu hingga aplikasi klien menerima frame server setup_complete dan mengonfigurasi HistoryConfig(initial_history_in_client_content=True).

Bermigrasi ke Gemini 3.8 Live

Untuk mengetahui informasi selengkapnya tentang migrasi dari gemini-live-2.5-flash-native-audio ke gemini-3.8-live, lihat Bermigrasi dari Gemini 2.5 Flash Live API Native Audio ke Gemini 3.8 Live.

Checklist developer

Verifikasi item berikut sebelum men-deploy aplikasi Anda:

Referensi lainnya

Untuk informasi selengkapnya, lihat referensi berikut:

• Halaman model Gemini 3.8 Live
• Mengonfigurasi avatar live
• Praktik terbaik dengan Gemini Live API
• Bermigrasi dari Gemini 2.5 Flash Live API Native Audio ke Gemini 3.8 Live
• Tutorial Python Gemini Live API
• Pengantar notebook Avatar Live
• Keterampilan Layanan Gemini Live API