Multimodal Live API

Multimodal Live API, Gemini ile düşük gecikmeli iki yönlü ses ve video etkileşimi sağlar. Multimodal Live API'yi kullanarak son kullanıcılara doğal, insana benzeyen 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.

Çoklu Formatlı Canlı API'yi Google AI Studio'da deneyebilirsiniz.

Multimodal Live API'yi kullanma

Bu bölümde, Multimodal 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 aşağıdaki WebSockets API referansı bölümüne bakın.

Metin gönderme ve alma

import asyncio
from google import genai

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

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(input=message, end_of_turn=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-exp"

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(input=message, end_of_turn=True)

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

            # Comment this out 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

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

from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(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

Multimodal Live API şu sesleri destekler: Aoede, Charon, Fenrir, Kore ve Puck.

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

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

Multimodal Live 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(input="Turn the lights down to a romantic level", end_of_turn=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ı bir ortamda yürütülerek sonraki BidiGenerateContentToolCall iletilerini oluşturur. Yürütme, her işlev çağrısının sonuçları hazır olana kadar duraklatılır. Bu sayede sıralı işleme sağlanır.

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

Ses girişleri ve ses çıkışları, modelin işlev çağrısı kullanma özelliğini 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 not None:
        # The generation was interrupted

Sınırlamalar

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

İstemci kimlik doğrulaması

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

Görüşme geçmişi

Model, oturum içi etkileşimleri takip eder ancak ileti dizisi geçmişi depolanmaz. Bir oturum sona erdiğinde ilgili bağlam silinir.

Önceki bir oturumu geri yüklemek veya modele kullanıcı etkileşimlerinin geçmiş bağlamını sağlamak için uygulamanın kendi sohbet günlüğünü tutması ve bu bilgileri yeni bir oturumun başında göndermek için bir BidiGenerateContentClientContent mesajı kullanması gerekir.

Maksimum oturum süresi

Oturum süresi, ses için en fazla 15 dakika veya ses ve video için en fazla 2 dakika ile sınırlıdır. Oturum süresi sınırı aşıldığında bağlantı sonlandırılır.

Model, bağlam boyutuyla da sınırlıdır. Video ve ses akışlarının yanı sıra büyük miktarda içerik göndermek, oturumun daha erken sonlandırılmasına neden olabilir.

Ses etkinliği algılama (VAD)

Model, sürekli bir ses girişi akışında otomatik olarak ses etkinliği algılama (VAD) işlemi gerçekleştirir. VAD her zaman etkindir ve parametreleri yapılandırılamaz.

Jeton sayısı

Jeton sayısı desteklenmez.

Hız sınırları

Aşağıdaki hız sınırları geçerlidir:

• API anahtarı başına 3 eşzamanlı oturum
• Dakikada 4 milyon jeton

WebSockets API referansı

Multimodal Live API, WebSockets kullanan durum bilgisine sahip bir API'dir. Bu bölümde, WebSockets API ile ilgili ek ayrıntılar bulabilirsiniz.

Oturum sayısı

WebSocket bağlantısı, istemci ile Gemini sunucusu arasında bir oturum oluşturur. Bir istemci yeni bir bağlantı başlattıktan sonra oturum, sunucuyla mesaj alışverişinde bulunarak şunları yapabilir:

• Gemini sunucusuna metin, ses veya video gönderme.
• Gemini sunucusundan ses, metin veya işlev çağrısı istekleri alma

Bağlantı kurulduktan sonraki ilk mesaj, model, oluşturma parametreleri, sistem talimatları ve araçları içeren oturum yapılandırmasını ayarlar.

Aşağıdaki örnek yapılandırmaya bakın. SDK'lardaki ad büyük/küçük harf kullanımında farklılıklar olabileceğini unutmayın. Python SDK yapılandırma seçeneklerini buradan inceleyebilirsiniz.

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

Mesaj gönderin

WebSocket bağlantısı üzerinden mesaj alışverişi yapmak için istemcinin açık bir WebSocket bağlantısı üzerinden JSON nesnesi göndermesi gerekir. JSON nesnesi, aşağıdaki nesne grubundaki alanlardan tam olarak birine sahip olmalıdır:

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Desteklenen istemci mesajları

Desteklenen istemci mesajlarını aşağıdaki tabloda görebilirsiniz:

İleti alma

Gemini'den mesaj almak için WebSocket "mesaj" etkinliğini dinleyin ve ardından sonucu, desteklenen sunucu mesajlarının tanımına göre ayrıştırın.

Aşağıdakilere bakın:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Sunucu mesajlarında aşağıdaki nesne grubundan tam olarak bir alan bulunur:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
}

Desteklenen sunucu mesajları

Desteklenen sunucu mesajlarını aşağıdaki tabloda görebilirsiniz:

Mesajlar ve etkinlikler

Yaygın türler hakkında daha fazla bilgi

Sık kullanılan API kaynak türleri Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata ve Tool hakkında daha fazla bilgi edinmek için İçerik oluşturma başlıklı makaleyi inceleyin.

Üçüncü taraf entegrasyonları

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

• Günlük
• Livekit