Live API

Live API, Gemini ile düşük gecikmeli iki yönlü ses ve görüntü etkileşimi sağlar. Live API'yi kullanarak son kullanıcılara doğal, insan benzeri sesli sohbet deneyimi ve sesli komutlar kullanarak modelin yanıtlarını kesintiye uğratma olanağı sunabilirsiniz. Model, metin, ses ve video girişini işleyebilir ve metin ile ses çıkışı sağlayabilir.

Canlı API'yi Google AI Studio'da deneyebilirsiniz.

Yenilikler

Live API'de yeni özellikler ve özellikler var.

Yeni özellikler:

• Yapılandırılabilir çıkış dili ile iki yeni ses ve 30 yeni dil
• Yapılandırılabilir resim çözünürlükleri 66/256 jeton
• Yapılandırılabilir konuşma kapsamı: Tüm girişleri her zaman veya yalnızca kullanıcı konuşurken gönderin
• Girişlerin modeli kesintiye uğratıp uğratmayacağını yapılandırma
• Yapılandırılabilir konuşma etkinliği algılama ve sıra sonu sinyali için yeni istemci etkinlikleri
• Jeton sayıları
• Akış sonunu bildirmek için bir istemci etkinliği
• Metin aktarımı
• Oturum verileri 24 saat boyunca sunucuda depolanarak yapılandırılabilir oturum devam ettirme
• Kaydırılabilir bağlam penceresiyle daha uzun oturum desteği

Yeni müşteri etkinlikleri:

• Ses aktarımının sonu / mikrofon kapalı
• Dönüş geçişini manuel olarak kontrol etmek için etkinlik başlangıç/bitiş etkinlikleri

Yeni sunucu etkinlikleri:

• Oturumun yeniden başlatılması gerektiğini belirten bildirim
• Oluşturma işlemi tamamlandı

Live API'yi kullanma

Bu bölümde, Live API'nin SDK'larımızdan biriyle nasıl kullanılacağı açıklanmaktadır. Temel WebSockets API hakkında daha fazla bilgi için WebSockets API referansı başlıklı makaleyi inceleyin.

Metin gönderme ve alma

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

Ses alma

Aşağıdaki örnekte, ses verilerinin nasıl alınacağı ve .wav dosyasına nasıl yazılacağı gösterilmektedir.

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

Ses biçimleri

Live API aşağıdaki ses biçimlerini destekler:

• Giriş ses biçimi: 16 kHz little-endian'da ham 16 bit PCM ses
• Çıkış ses biçimi: 24 kHz little-endian'da ham 16 bit PCM ses

Ses ve video aktarma

Sistem talimatları

Sistem talimatları, bir modelin davranışını belirli ihtiyaçlarınıza ve kullanım alanlarınıza göre yönlendirmenize olanak tanır. Sistem talimatları, kurulum yapılandırmasında ayarlanabilir ve oturum boyunca geçerli kalır.

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"],
}

Artımlı içerik güncellemeleri

Metin girişi göndermek, oturum bağlamı oluşturmak veya oturum bağlamını geri yüklemek için artımlı güncellemeleri kullanın. Kısa bağlamlarda, tam etkinlik sırasını temsil etmek için adım adım etkileşimler gönderebilirsiniz:

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

Daha uzun bağlamlarda, sonraki etkileşimler için bağlam penceresini boşaltmak amacıyla tek bir mesaj özeti sağlamanız önerilir.

Sesleri değiştirme

Live API şu sesleri destekler: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus ve Zephyr.

Ses belirlemek için oturum yapılandırmasının bir parçası olarak speechConfig nesnesinde ses adını ayarlayın:

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

Dili değiştir

Live API birden fazla dili destekler.

Dili değiştirmek için oturum yapılandırmasının bir parçası olarak speechConfig nesnesinde dil kodunu ayarlayın:

from google.genai import types

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

İşlev çağrısını kullanma

Canlı API ile araçları tanımlayabilirsiniz. İşlev çağırma hakkında daha fazla bilgi edinmek için İşlev çağırma eğitimi başlıklı makaleyi inceleyin.

Araçlar, oturum yapılandırmasının bir parçası olarak tanımlanmalıdır:

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)

Model, tek bir istemden birden fazla işlev çağrısı ve çıktılarını zincirlemek için gereken kodu oluşturabilir. Bu kod, korumalı alanda yürütülür ve ardından BidiGenerateContentToolCall iletileri oluşturur. Yürütme, her işlev çağrısının sonuçları hazır olana kadar duraklatılır. Bu, sıralı işleme sağlar.

Müşteri, BidiGenerateContentToolResponse ile yanıt vermelidir.

Ses girişleri ve ses çıkışları, modelin işlev çağırma özelliğini kullanabilme durumunu olumsuz etkiler.

Kesintileri ele alma

Kullanıcılar istedikleri zaman modelin çıktısını kesintiye uğratabilir. Ses etkinliği algılama (VAD) bir kesinti algıladığında, devam eden oluşturma işlemi iptal edilir ve atılır. Oturum geçmişinde yalnızca istemciye gönderilmiş olan bilgiler saklanır. Ardından sunucu, kesintiyi bildirmek için bir BidiGenerateContentServerContent mesajı gönderir.

Ayrıca Gemini sunucusu, bekleyen tüm işlev çağrılarını atar ve iptal edilen çağrıların kimliklerini içeren bir BidiGenerateContentServerContent mesajı gönderir.

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

Ses etkinliği algılamayı (VAD) yapılandırma

Model varsayılan olarak sürekli bir ses girişi akışında ses etkinliği algılama (VAD) işlemini otomatik olarak gerçekleştirir. VAD, kurulum yapılandırmasının realtimeInputConfig.automaticActivityDetection alanıyla yapılandırılabilir.

Ses akışı bir saniyeden uzun süre duraklatıldığında (örneğin, kullanıcı mikrofonu kapattığı için), önbelleğe alınan seslerin temizlenmesi için bir audioStreamEnd etkinliği gönderilmelidir. İstemci, ses verilerini göndermeyi istediği zaman devam ettirebilir.

Alternatif olarak, otomatik VAD, kurulum mesajında realtimeInputConfig.automaticActivityDetection.disabled değerini true olarak ayarlayarak devre dışı bırakılabilir. Bu yapılandırmada istemci, kullanıcı konuşmasını algılamaktan ve uygun zamanlarda activityStart ile activityEnd mesajları göndermekten sorumludur. Bu yapılandırmada audioStreamEnd gönderilmez. Bunun yerine, akışın kesintiye uğraması activityEnd mesajıyla işaretlenir.

Bu özellik için SDK desteği önümüzdeki haftalarda kullanıma sunulacak.

Jeton sayısını alma

Kullanılan jetonların toplam sayısını, döndürülen sunucu mesajının usageMetadata alanında bulabilirsiniz.

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}")

Oturum süresini uzatma

Maksimum oturum süresi, iki mekanizmayla sınırsız olarak uzatılabilir:

• Bağlam penceresi sıkıştırmayı etkinleştirme
• Oturum devam ettirme özelliğini yapılandırma

Ayrıca oturum sona ermeden önce GoAway mesajı alırsınız. Bu mesaj, daha fazla işlem yapmanıza olanak tanır.

Bağlam penceresi sıkıştırmasını etkinleştirin

Daha uzun oturumlar etkinleştirmek ve bağlantının aniden kesilmesini önlemek için oturum yapılandırmasının bir parçası olarak contextWindowCompression alanını ayarlayarak bağlam penceresi sıkıştırmasını etkinleştirebilirsiniz.

ContextWindowCompressionConfig'de, sıkıştırmayı tetikleyen bir kaydırma aralığı mekanizmasını ve jeton sayısını yapılandırabilirsiniz.

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(),
        )
    ),
)

Oturum devam ettirme özelliğini yapılandırma

Sunucu, WebSocket bağlantısını düzenli olarak sıfırladığında oturumun sonlandırılmasını önlemek için kurulum yapılandırması içinde sessionResumption alanını yapılandırın.

Bu yapılandırma iletildiğinde sunucu, SessionResumptionUpdate mesajları gönderir. Bu mesajlar, sonraki bağlantının SessionResumptionConfig.handle olarak son devam ettirme jetonunu ileterek oturumu devam ettirmek için kullanılabilir.

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

Oturum bağlantısı kesilmeden önce mesaj alma

Sunucu, mevcut bağlantının yakında sonlandırılacağını belirten bir GoAway mesajı gönderir. Bu mesaj, kalan süreyi belirten timeLeft değerini içerir ve bağlantı ABORTED olarak sonlandırılmadan önce başka işlemler yapmanıza olanak tanır.

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)

Oluşturma işlemi tamamlandığında mesaj alma

Sunucu, modelin yanıtı oluşturmayı tamamladığını belirten bir generationComplete mesajı gönderir.

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

Medya çözünürlüğünü değiştirme

Oturum yapılandırmasının bir parçası olarak mediaResolution alanını ayarlayarak giriş medyası için medya çözünürlüğünü belirtebilirsiniz:

from google.genai import types

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

Sınırlamalar

Projenizi planlarken Live API ve Gemini 2.0'ın aşağıdaki sınırlamalarını göz önünde bulundurun.

Yanıt modları

Oturum yapılandırmasında oturum başına yalnızca bir yanıt modu (TEXT veya AUDIO) ayarlayabilirsiniz. İkisini de ayarlamaya çalışmak yapılandırma hatası mesajıyla sonuçlanır. Bu, modeli metin veya sesle yanıt verecek şekilde yapılandırabileceğiniz ancak aynı oturumda ikisini birden kullanamayacağınız anlamına gelir.

İstemci kimlik doğrulaması

Live API yalnızca sunucudan sunucuya kimlik doğrulama sağlar ve doğrudan istemci kullanımı için önerilmez. İstemci girişi, Live API ile güvenli kimlik doğrulama için bir ara uygulama sunucusu üzerinden yönlendirilmelidir.

Oturum süresi

Oturum sıkıştırması etkinleştirilerek oturum süresi sınırsız olarak uzatılabilir. Sıkıştırma olmadan, yalnızca sesli oturumlar 15 dakikayla, sesli ve görüntülü oturumlar ise 2 dakikayla sınırlıdır. Sıkıştırma olmadan bu sınırlar aşıldığında bağlantı sonlandırılır.

Ayrıca, istemcinin sonlandırılan bir oturumu devam ettirmesine izin vermek için oturum devam ettirme özelliğini yapılandırabilirsiniz.

Bağlam penceresi

Oturumların bağlam penceresi sınırı 32 bin parçadır.

Desteklenen diller

Live API aşağıdaki dilleri destekler:

Üçüncü taraf entegrasyonları

Web ve mobil uygulama dağıtımları için aşağıdaki seçenekleri inceleyebilirsiniz:

• Günlük
• Livekit