Live API

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. Model ini dapat memproses input teks, audio, dan video, serta dapat memberikan output teks dan audio.

Anda dapat mencoba Live API di Google AI Studio.

Yang baru

Live API memiliki fitur dan kemampuan baru.

Kemampuan baru:

• Dua suara baru dan 30 bahasa baru, dengan bahasa output yang dapat dikonfigurasi
• Resolusi gambar yang dapat dikonfigurasi 66/256 token
• Cakupan belokan yang dapat dikonfigurasi: Mengirim semua input setiap saat atau hanya saat pengguna berbicara
• Mengonfigurasi apakah input harus mengganggu model atau tidak
• Deteksi Aktivitas Suara yang dapat dikonfigurasi dan peristiwa klien baru untuk sinyal akhir gilir
• Jumlah token
• Peristiwa klien untuk menandai akhir streaming
• Streaming teks
• Lanjutan sesi yang dapat dikonfigurasi, dengan data sesi yang disimpan di server selama 24 jam
• Dukungan sesi yang lebih lama dengan jendela konteks geser

Peristiwa klien baru:

• Akhir streaming audio / mikrofon ditutup
• Peristiwa awal/akhir aktivitas untuk mengontrol transisi belokan secara manual

Peristiwa server baru:

• Notifikasi pergi yang menandakan perlunya memulai ulang sesi
• Pembuatan selesai

Menggunakan Live API

Bagian ini menjelaskan cara menggunakan Live API dengan salah satu SDK kami. Untuk informasi selengkapnya tentang WebSockets API yang mendasarinya, lihat Referensi WebSockets API.

Mengirim dan menerima teks

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
            )

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

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

Menerima audio

Contoh berikut menunjukkan cara menerima data audio dan menulisnya ke file .wav.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-live-001"

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Un-comment this code to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

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

Format audio

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

Melakukan streaming audio dan video

Petunjuk sistem

Petunjuk sistem memungkinkan Anda mengarahkan perilaku model berdasarkan kebutuhan dan kasus penggunaan tertentu. Petunjuk sistem dapat ditetapkan dalam konfigurasi penyiapan dan akan tetap berlaku selama seluruh sesi.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

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:

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)

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

Untuk konteks yang lebih panjang, sebaiknya berikan ringkasan pesan tunggal untuk mengosongkan jendela konteks untuk interaksi berikutnya.

Mengubah suara

Live API mendukung suara berikut: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, dan Zephyr.

Untuk menentukan suara, tetapkan nama suara dalam objek speechConfig sebagai bagian dari konfigurasi sesi:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Ubah bahasa

Live API mendukung beberapa bahasa.

Untuk mengubah bahasa, tetapkan kode bahasa dalam objek speechConfig sebagai bagian dari konfigurasi sesi:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

Menggunakan panggilan fungsi

Anda dapat menentukan alat dengan Live API. Lihat Tutorial panggilan fungsi untuk mempelajari panggilan fungsi lebih lanjut.

Alat harus ditentukan sebagai bagian dari konfigurasi sesi:

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send_client_content(
        turns={
            "role": "user",
            "parts": [{"text": "Turn the lights down to a romantic level"}],
        },
        turn_complete=True,
    )

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

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

Klien harus merespons dengan BidiGenerateContentToolResponse.

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

Menangani 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 mengirimkan pesan BidiGenerateContentServerContent untuk melaporkan gangguan.

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

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

Mengonfigurasi 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 konfigurasi penyiapan.

Saat streaming audio dijeda selama lebih dari satu detik (misalnya, karena pengguna menonaktifkan mikrofon), peristiwa audioStreamEnd harus 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.

Dukungan SDK untuk fitur ini akan tersedia dalam beberapa minggu ke depan.

Mendapatkan jumlah token

Anda dapat menemukan jumlah total token yang digunakan di kolom usageMetadata dari pesan server yang ditampilkan.

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

Memperpanjang durasi sesi

Durasi sesi maksimum dapat diperpanjang menjadi tanpa batas dengan dua mekanisme:

• Mengaktifkan kompresi jendela konteks
• Mengonfigurasi kelanjutan sesi

Selain itu, Anda akan menerima pesan GoAway sebelum sesi berakhir, sehingga Anda dapat mengambil tindakan lebih lanjut.

Mengaktifkan kompresi jendela konteks

Untuk mengaktifkan sesi yang lebih lama, dan menghindari penghentian koneksi secara tiba-tiba, Anda dapat mengaktifkan kompresi jendela konteks dengan menetapkan kolom contextWindowCompression sebagai bagian dari konfigurasi sesi.

Di ContextWindowCompressionConfig, Anda dapat mengonfigurasi mekanisme jendela geser dan jumlah token yang memicu kompresi.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Mengonfigurasi kelanjutan sesi

Untuk mencegah penghentian sesi saat server mereset koneksi WebSocket secara berkala, konfigurasikan kolom sessionResumption dalam konfigurasi penyiapan.

Meneruskan konfigurasi ini akan menyebabkan server mengirim pesan SessionResumptionUpdate, yang dapat digunakan untuk melanjutkan sesi dengan meneruskan token lanjutan terakhir sebagai SessionResumptionConfig.handle koneksi berikutnya.

from google.genai import types

print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
    model="gemini-2.0-flash-live-001",
    config=types.LiveConnectConfig(
        response_modalities=["AUDIO"],
        session_resumption=types.SessionResumptionConfig(
            # The handle of the session to resume is passed here,
            # or else None to start a new session.
            handle=previous_session_handle
        ),
    ),
) as session:
    # Session connected
    while True:
        await session.send_client_content(
            turns=types.Content(
                role="user", parts=[types.Part(text="Hello world!")]
            )
        )
        async for message in session.receive():
            # Periodically, the server will send update messages that may
            # contain a handle for the current state of the session.
            if message.session_resumption_update:
                update = message.session_resumption_update
                if update.resumable and update.new_handle:
                    # The handle should be retained and linked to the session.
                    return update.new_handle

            # For the purposes of this example, placeholder input is continually fed
            # to the model. In non-sample code, the model inputs would come from
            # the user.
            if message.server_content and message.server_content.turn_complete:
                break

Menerima pesan sebelum sesi terputus

Server mengirim pesan GoAway yang menandakan bahwa koneksi saat ini akan segera dihentikan. Pesan ini menyertakan timeLeft, yang menunjukkan waktu yang tersisa dan memungkinkan Anda mengambil tindakan lebih lanjut sebelum koneksi dihentikan sebagai ABORTED.

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

Menerima pesan saat pembuatan selesai

Server mengirimkan pesan generationComplete yang menandakan bahwa model telah selesai membuat respons.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

Mengubah resolusi media

Anda dapat menentukan resolusi media untuk media input dengan menetapkan kolom mediaResolution sebagai bagian dari konfigurasi sesi:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Batasan

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

Modalitas respons

Anda hanya dapat menetapkan satu modalitas respons (TEXT atau AUDIO) per sesi dalam konfigurasi sesi. Mencoba menetapkan keduanya akan menghasilkan pesan error konfigurasi. Artinya, Anda dapat mengonfigurasi model untuk merespons dengan teks atau audio, tetapi tidak keduanya dalam sesi yang sama.

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

Durasi sesi dapat diperpanjang menjadi tidak terbatas dengan mengaktifkan kompresi sesi. Tanpa kompresi, sesi audio saja dibatasi hingga 15 menit, dan sesi audio plus video dibatasi hingga 2 menit. Jika batas ini terlampaui tanpa kompresi, koneksi akan dihentikan.

Selain itu, Anda dapat mengonfigurasi lanjutan sesi untuk memungkinkan klien melanjutkan sesi yang dihentikan.

Jendela konteks

Sesi memiliki batas jendela konteks 32 ribu token.

Bahasa yang didukung

Live API mendukung bahasa berikut:

Integrasi pihak ketiga

Untuk deployment aplikasi web dan seluler, Anda dapat menjelajahi opsi dari:

• Setiap hari
• Livekit