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:

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

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

Mesaj Açıklama
BidiGenerateContentSetup İlk mesajda gönderilecek oturum yapılandırması
BidiGenerateContentClientContent İstemciden gönderilen mevcut sohbetin artımlı içerik güncellemesi
BidiGenerateContentRealtimeInput Gerçek zamanlı ses veya video girişi
BidiGenerateContentToolResponse Sunucudan alınan ToolCallMessage yanıtı

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

Mesaj Açıklama
BidiGenerateContentSetupComplete Kurulum tamamlandığında istemciden gönderilen bir BidiGenerateContentSetup mesajı
BidiGenerateContentServerContent Müşteri mesajına yanıt olarak model tarafından oluşturulan içerik
BidiGenerateContentToolCall İstemcinin işlev çağrılarını çalıştırmasını ve yanıtları eşleşen kimliklerle döndürmesini isteme
BidiGenerateContentToolCallCancellation Kullanıcı model çıkışını kesintiye uğrattığı için bir işlev çağrısı iptal edildiğinde gönderilir

Mesajlar ve etkinlikler

BidiGenerateContentClientContent

İstemciden gönderilen mevcut sohbetin artımlı güncellemesi. Buradaki tüm içerikler koşulsuz olarak ileti dizisine eklenir ve içerik oluşturmak için modele verilen istemin bir parçası olarak kullanılır.

Buradaki bir mesaj, mevcut model oluşturma işlemini kesintiye uğratır.

Alanlar
turns[]

Content

İsteğe bağlı. Modelle olan mevcut görüşmeye eklenen içerik.

Tek turlu sorgular için bu tek bir örnektir. Birden fazla dönüş içeren sorgular için bu, sohbet geçmişini ve son isteği içeren yinelenen bir alandır.

turn_complete

bool

İsteğe bağlı. Doğru ise sunucu içeriği oluşturma işleminin, şu anda birikmiş istemle başlaması gerektiğini belirtir. Aksi takdirde sunucu, oluşturma işlemini başlatmadan önce ek mesaj bekler.

BidiGenerateContentRealtimeInput

Gerçek zamanlı olarak gönderilen kullanıcı girişi.

Bu, BidiGenerateContentClientContent ile birkaç açıdan farklıdır:

  • Model oluşturma işlemine kesinti vermeden sürekli olarak gönderilebilir.
  • BidiGenerateContentClientContent ve BidiGenerateContentRealtimeInput arasında ardışık olarak yerleştirilmiş verileri karıştırmak gerekirse sunucu en iyi yanıtı verecek şekilde optimizasyon yapmaya çalışır ancak bu konuda garanti verilmez.
  • Sıranın sonu açıkça belirtilmez, bunun yerine kullanıcı etkinliğinden (ör. konuşmanın sonu) türetilir.
  • Dönüş bitmeden önce bile veriler, modelden gelen yanıtın hızlı bir şekilde başlatılması için optimize edilmek üzere artımlı olarak işlenir.
  • Her zaman kullanıcının girişi olarak kabul edilir (ileti dizisi geçmişini doldurmak için kullanılamaz). Kesintisiz olarak sürekli gönderilebilir. Model, kullanıcı konuşmasının başlangıcını ve sonunu otomatik olarak algılar ve yanıtın aktarılmasını buna göre başlatır veya sonlandırır. Veriler, geldikçe artımlı olarak işlenir ve gecikme en aza indirilir.
Alanlar
media_chunks[]

Blob

İsteğe bağlı. Medya girişi için satır içi bayt verileri.

BidiGenerateContentServerContent

İstemci mesajlarına yanıt olarak model tarafından oluşturulan artımlı sunucu güncellemesi.

İçerik, gerçek zamanlı olarak değil, mümkün olduğunca hızlı bir şekilde oluşturulur. İstemciler, içeriği arabelleğe alıp gerçek zamanlı olarak oynatmayı seçebilir.

Alanlar
turn_complete

bool

Yalnızca çıkış. True (Doğru) ise modelin oluşturulmasının tamamlandığını gösterir. Oluşturma işlemi yalnızca ek istemci mesajlarına yanıt olarak başlar. content ile birlikte ayarlanabilir. Bu durumda, content'ün sıranın sonundaki öğe olduğunu belirtir.

interrupted

bool

Yalnızca çıkış. Doğru ise bir istemci mesajının mevcut model oluşturma işlemini kesintiye uğrattığını gösterir. İstemci içeriği gerçek zamanlı olarak oynatıyorsa bu, oynatmayı durdurup mevcut oynatma sırasını boşaltmak için iyi bir sinyaldir.

grounding_metadata

GroundingMetadata

Yalnızca çıkış. Oluşturulan içerik için temel meta veriler.

model_turn

Content

Yalnızca çıkış. Modelin, kullanıcıyla devam eden görüşmenin bir parçası olarak oluşturduğu içerik.

BidiGenerateContentSetup

İlk ve tek istemci mesajında gönderilecek mesaj. Akış oturumu boyunca geçerli olacak yapılandırmayı içerir.

Müşteriler, ek mesaj göndermeden önce bir BidiGenerateContentSetupComplete mesajı beklemelidir.

Alanlar
model

string

Zorunlu. Modelin kaynak adı. Bu, modelin kullanacağı bir kimlik görevi görür.

Biçim: models/{model}

generation_config

GenerationConfig

İsteğe bağlı. Oluşturma yapılandırması.

Aşağıdaki alanlar desteklenmez:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_instruction

Content

İsteğe bağlı. Kullanıcı, model için sistem talimatları sağladı.

Not: Parçalarda yalnızca metin kullanılmalıdır. Her bölümdeki içerik ayrı bir paragrafta yer alır.

tools[]

Tool

İsteğe bağlı. Modelin sonraki yanıtı oluşturmak için kullanabileceği Tools öğelerinin listesi.

Tool, sistemin modelin bilgisi ve kapsamı dışında bir işlem veya işlem grubu gerçekleştirmek için harici sistemlerle etkileşime geçmesini sağlayan bir kod parçasıdır.

BidiGenerateContentSetupComplete

Bu türde alan yoktur.

İstemciden gelen bir BidiGenerateContentSetup mesajına yanıt olarak gönderilir.

BidiGenerateContentToolCall

İstemciden işlev çağrılarını yürütmesini ve eşleşen id ile yanıtları döndürmesini isteyin.

Alanlar
function_calls[]

FunctionCall

Yalnızca çıkış. Yürütülecek işlev çağrısı.

BidiGenerateContentToolCallCancellation

Belirtilen id'ler içeren daha önce verilen bir ToolCallMessage'nin yürütülmemesi ve iptal edilmesi gerektiğini müşteriye bildiren bildirim. Bu araç çağrılarının yan etkileri varsa istemciler araç çağrılarını geri almaya çalışabilir. Bu mesaj yalnızca istemcilerin sunucu sırasını kesintiye uğrattığı durumlarda gösterilir.

Alanlar
ids[]

string

Yalnızca çıkış. İptal edilecek araç çağrılarının kimlikleri.

BidiGenerateContentToolResponse

Sunucudan alınan bir ToolCall için istemci tarafından oluşturulan yanıt. Ayrı FunctionResponse nesneleri, id alanı tarafından ilgili FunctionCall nesneleriyle eşleştirilir.

Tek değerli ve sunucudan aktarılan GenerateContent API'lerinde işlev çağrısının Content parçalarının değiştirilmesiyle gerçekleştiğini, çift yönlü GenerateContent API'lerinde ise işlev çağrısının bu özel mesaj grubu üzerinden gerçekleştiğini unutmayın.

Alanlar
function_responses[]

FunctionResponse

İsteğe bağlı. İşlev çağrılarına verilen yanıt.

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: