Live API özellikleri kılavuzu

Bu, Canlı API ile kullanılabilen yetenekleri ve yapılandırmaları kapsayan kapsamlı bir kılavuzdur. Genel bir bakış ve yaygın kullanım durumları için örnek kodlar için Canlı API ile Başlayın sayfasına bakın.

Başlamadan önce

  • Temel kavramlara aşina olun: Henüz yapmadıysanız, önce Canlı API ile çalışmaya başlayın sayfasını okuyun. Bu doküman, Canlı API'nin temel ilkeleri, nasıl çalıştığı ve farklı uygulama yaklaşımları hakkında bilgi verir.
  • AI Studio'da Canlı API'yi deneyin: Geliştirmeye başlamadan önce Google AI Studio'da Canlı API'yi denemeniz faydalı olabilir. Google AI Studio'da Live API'yi kullanmak için Stream'i (Yayın) seçin.

Model karşılaştırma

Aşağıdaki tablo, Gemini 3.1 Flash Canlı Önizleme ve Gemini 2.5 Flash Canlı Önizleme modelleri arasındaki temel farklılıkları özetlemektedir:

Özellik Gemini 3.1 Flash Live Preview Gemini 2.5 Flash Live Preview
Düşünme (Thinking) thinkingLevel kullanarak minimal, low, medium ve high gibi ayarlarla düşünme derinliğini kontrol eder. En düşük gecikme süresi için optimizasyon amacıyla varsayılan olarak minimal seçilir. Düşünme seviyeleri ve bütçeler başlıklı makaleyi inceleyin. Düşünme belirteçlerinin sayısını ayarlamak için thinkingBudget kullanılır. Dinamik düşünme özelliği varsayılan olarak etkindir. Devre dışı bırakmak için thinkingBudget değerini 0 olarak ayarlayın. Düşünme seviyeleri ve bütçeler başlıklı makaleyi inceleyin.
Yanıt alınıyor Tek bir sunucu etkinliği aynı anda birden fazla içerik bölümü (ör. inlineData ve transkript) içerebilir. İçerik eksikliği yaşamamak için kodunuzun her etkinlikteki tüm bölümleri işlediğinden emin olun. Her sunucu etkinliği yalnızca bir içerik bölümü içerir. Parçalar ayrı etkinlikler halinde yayınlanır.
Müşteri içeriği send_client_content yalnızca ilk bağlam geçmişini başlatmak için desteklenir (oturum yapılandırmasında initial_history_in_client_content ayarının yapılması gerekir). Görüşme sırasında metin güncellemeleri göndermek için bunun yerine send_realtime_input simgesini kullanın. send_client_content, artımlı içerik güncellemeleri göndermek ve bağlam oluşturmak için görüşme boyunca desteklenir.
Dönüş kapsamı Varsayılan olarak TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO değerine ayarlanır. Modelin dönüşü, algılanan ses etkinliğini ve tüm video karelerini içerir. Varsayılan olarak TURN_INCLUDES_ONLY_ACTIVITY değerine ayarlanır. Modelin yanıtı yalnızca algılanan etkinliği içerir.
Özel VAD (activity_start/activity_end) Desteklenir. Dönüşüm sınırlarını kontrol etmek için otomatik VAD'yi devre dışı bırakın ve activityStart ile activityEnd mesajlarını manuel olarak gönderin. Desteklenir. Dönüşüm sınırlarını kontrol etmek için otomatik VAD'yi devre dışı bırakın ve activityStart ile activityEnd mesajlarını manuel olarak gönderin.
Otomatik VAD yapılandırması Desteklenir. start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms ve silence_duration_ms gibi parametreleri yapılandırın. Desteklenir. start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms ve silence_duration_ms gibi parametreleri yapılandırın.
Eşzamansız işlev çağrısı (behavior: NON_BLOCKING) Desteklenmez. İşlev çağırma yalnızca sıralı olarak yapılabilir. Model, araç yanıtını gönderene kadar yanıt vermeye başlamaz. Desteklenir. İşlev çalışırken modelin etkileşime devam etmesine izin vermek için işlev tanımlamasında behavior değerini NON_BLOCKING olarak ayarlayın. scheduling parametresiyle (INTERRUPT, WHEN_IDLE veya SILENT) modelin yanıtları nasıl işleyeceğini kontrol edin.
Proaktif ses Desteklenmiyor Desteklenir. Etkinleştirildiğinde model, giriş içeriği alakalı değilse yanıt vermemeye proaktif olarak karar verebilir. proactivity yapılandırmasında proactive_audio değerini true olarak ayarlayın (v1beta gerektirir).
Duygusal diyalog (Affective dialogue) Desteklenmiyor Desteklenir. Model, yanıt stilini girişin ifadesine ve üslubuna uyacak şekilde düzenler. Oturum yapılandırmasında enable_affective_dialog değerini true olarak ayarlayın (v1beta gerektirir).

Gemini 2.5 Flash Live'dan Gemini 3.1 Flash Live'a geçiş yapmak için taşıma kılavuzuna bakın.

Bağlantı kurma

Aşağıdaki örnekte, API anahtarıyla nasıl bağlantı oluşturulacağı gösterilmektedir:

Python

import asyncio
from google import genai

client = genai.Client()

model = "gemini-3.1-flash-live-preview"
config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started")
        # Send content...

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        console.debug(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  console.debug("Session started");
  // Send content...

  session.close();
}

main();

Etkileşim biçimleri

Aşağıdaki bölümlerde, Canlı API'de bulunan farklı giriş ve çıkış yöntemleriyle ilgili örnekler ve destekleyici bağlamlar verilmektedir.

Ses gönderme

Ses, ham PCM verileri (ham 16 bit PCM ses, 16 kHz, little-endian) olarak gönderilmelidir.

Python

# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)

JavaScript

// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
  audio: {
    data: chunk.toString('base64'),
    mimeType: 'audio/pcm;rate=16000'
  }
});

Ses biçimleri

Live API'deki ses verileri her zaman ham, little-endian ve 16 bit PCM'dir. Ses çıkışında her zaman 24 kHz örnekleme hızı kullanılır. Giriş sesi, doğal olarak 16 kHz'dir ancak gerekirse Live API yeniden örnekleme yapacağından herhangi bir örnekleme hızı gönderilebilir. Giriş sesinin örnekleme hızını iletmek için ses içeren her Blob'un MIME türünü audio/pcm;rate=16000 gibi bir değere ayarlayın.

Ses alma

Modelin sesli yanıtları veri parçaları olarak alınır.

Python

async for response in session.receive():
    if response.server_content and response.server_content.model_turn:
        for part in response.server_content.model_turn.parts:
            if part.inline_data:
                audio_data = part.inline_data.data
                # Process or play the audio data

JavaScript

// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data;
      // Process or play audioData (base64 encoded string)
    }
  }
}

Kısa mesaj gönderiliyor

Metin, send_realtime_input (Python) veya sendRealtimeInput (JavaScript) kullanılarak gönderilebilir.

Python

await session.send_realtime_input(text="Hello, how are you?")

JavaScript

session.sendRealtimeInput({
  text: 'Hello, how are you?'
});

Video gönderiliyor

Video kareleri, belirli bir kare hızında (saniyede en fazla 1 kare) ayrı resimler (ör. JPEG veya PNG) olarak gönderilir.

Python

# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
    video=types.Blob(
        data=frame,
        mime_type="image/jpeg"
    )
)

JavaScript

// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
  video: {
    data: frame.toString('base64'),
    mimeType: 'image/jpeg'
  }
});

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ğlamlar için, etkinliklerin tam sırasını temsil etmek üzere adım adım etkileşimler gönderebilirsiniz:

Python

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)

JavaScript

let inputTurns = [
  { "role": "user", "parts": [{ "text": "What is the capital of France?" }] },
  { "role": "model", "parts": [{ "text": "Paris" }] },
]

session.sendClientContent({ turns: inputTurns, turnComplete: false })

inputTurns = [{ "role": "user", "parts": [{ "text": "What is the capital of Germany?" }] }]

session.sendClientContent({ turns: inputTurns, turnComplete: true })

Daha uzun metinler için, sonraki etkileşimler için metin penceresini boşaltmak amacıyla tek bir mesaj özeti sunulması önerilir. Oturum bağlamını yüklemek için başka bir yöntem için Oturum Yeniden Başlatma bölümüne bakın.

Sesten dönüştürülen metinler

Model yanıtına ek olarak, hem ses çıkışının hem de ses girişinin transkripsiyonlarını da alabilirsiniz.

Modelin ses çıkışının yazıya geçirilmesini etkinleştirmek için, kurulum yapılandırmasında output_audio_transcription gönderin. Modelin yanıtından transkripsiyon dili çıkarılır.

Python

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

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';

const config = {
  responseModalities: [Modality.AUDIO],
  outputAudioTranscription: {}
};

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'Hello how are you?';
  session.sendClientContent({ turns: inputTurns });

  const turns = await handleTurn();

  for (const turn of turns) {
    if (turn.serverContent && turn.serverContent.outputTranscription) {
      console.debug('Received output transcription: %s\n', turn.serverContent.outputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

Modelin ses girişinin yazıya geçirilmesini etkinleştirmek için, kurulum yapılandırmasında input_audio_transcription gönderin.

Python

import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_data = Path("16000.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_data, mime_type='audio/pcm;rate=16000')
        )

        async for msg in session.receive():
            if msg.server_content.input_transcription:
                print('Transcript:', msg.server_content.input_transcription.text)

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile';
const { WaveFile } = pkg;

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';

const config = {
  responseModalities: [Modality.AUDIO],
  inputAudioTranscription: {}
};

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  // Send Audio Chunk
  const fileBuffer = fs.readFileSync("16000.wav");

  // Ensure audio conforms to API requirements (16-bit PCM, 16kHz, mono)
  const wav = new WaveFile();
  wav.fromBuffer(fileBuffer);
  wav.toSampleRate(16000);
  wav.toBitDepth("16");
  const base64Audio = wav.toBase64();

  // If already in correct format, you can use this:
  // const fileBuffer = fs.readFileSync("sample.pcm");
  // const base64Audio = Buffer.from(fileBuffer).toString('base64');

  session.sendRealtimeInput(
    {
      audio: {
        data: base64Audio,
        mimeType: "audio/pcm;rate=16000"
      }
    }
  );

  const turns = await handleTurn();
  for (const turn of turns) {
    if (turn.text) {
      console.debug('Received text: %s\n', turn.text);
    }
    else if (turn.data) {
      console.debug('Received inline data: %s\n', turn.data);
    }
    else if (turn.serverContent && turn.serverContent.inputTranscription) {
      console.debug('Received input transcription: %s\n', turn.serverContent.inputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

Ses tonunu ve dilini değiştir

Yerel ses çıkışı modelleri, Metinden Sese (TTS) modellerimiz için mevcut olan tüm sesleri destekler. AI Studio'da tüm sesleri dinleyebilirsiniz.

Bir ses belirtmek için, oturum yapılandırmasının bir parçası olarak speechConfig nesnesi içinde ses adını ayarlayın:

Python

config = {
    "response_modalities": ["AUDIO"],
    "speech_config": {
        "voice_config": {"prebuilt_voice_config": {"voice_name": "Kore"}}
    },
}

JavaScript

const config = {
  responseModalities: [Modality.AUDIO],
  speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } }
};

Live API birden fazla dili destekler. Yerel ses çıkışı modelleri, uygun dili otomatik olarak seçer ve dil kodunun açıkça ayarlanmasını desteklemez.

Doğal ses özellikleri

En yeni modellerimizde doğal ses çıkışı özelliği bulunur. Bu özellik, doğal ve gerçekçi sesli konuşma ile çok dilli performansı iyileştirir.

Düşünen

Gemini 3.1 modelleri, düşünce derinliğini kontrol etmek için thinkingLevel kullanır. minimal, low, medium ve high gibi ayarlar vardır. En düşük gecikme süresi için varsayılan ayar minimal'dır. Gemini 2.5 modelleri, düşünme parçalarının sayısını ayarlamak için thinkingBudget kullanır. Seviyeler ve bütçeler hakkında daha fazla bilgi için Seviyeler ve bütçeler hakkında düşünme başlıklı makaleyi inceleyin.

Python 

model = "gemini-3.1-flash-live-preview"

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"]
    thinking_config=types.ThinkingConfig(
        thinking_level="low",
    )
)

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio input and receive audio

JavaScript

const model = 'gemini-3.1-flash-live-preview';
const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingLevel: 'low',
  },
};

async function main() {

  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: ...,
  });

  // Send audio input and receive audio

  session.close();
}

main();

Ayrıca, yapılandırmanızda includeThoughts değerini true olarak ayarlayarak düşünce özetlerini etkinleştirebilirsiniz. Daha fazla bilgi için düşünce özetleri bölümüne bakın:

Python 

model = "gemini-3.1-flash-live-preview"

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"]
    thinking_config=types.ThinkingConfig(
        thinking_level="low",
        include_thoughts=True
    )
)

JavaScript

const model = 'gemini-3.1-flash-live-preview';
const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingLevel: 'low',
    includeThoughts: true,
  },
};

Moda uygun diyalog

Bu özellik, Gemini'ın yanıt stilini giriş ifadesine ve tonuna göre uyarlamasını sağlar.

Duygusal diyaloğu kullanmak için API sürümünü v1beta olarak ayarlayın ve kurulum mesajında enable_affective_dialog değerini true olarak belirleyin:

Python

client = genai.Client(http_options={"api_version": "v1beta"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True
)

JavaScript

const ai = new GoogleGenAI({ httpOptions: {"apiVersion": "v1beta"} });

const config = {
  responseModalities: [Modality.AUDIO],
  enableAffectiveDialog: true
};

Proaktif ses

Bu özellik etkinleştirildiğinde Gemini, içerik alakalı değilse yanıt vermemeye proaktif olarak karar verebilir.

Kullanmak için API sürümünü v1beta olarak ayarlayın, kurulum mesajında proactivity alanını yapılandırın ve proactive_audio değerini true olarak ayarlayın:

Python

client = genai.Client(http_options={"api_version": "v1beta"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity={'proactive_audio': True}
)

JavaScript

const ai = new GoogleGenAI({ httpOptions: {"apiVersion": "v1beta"} });

const config = {
  responseModalities: [Modality.AUDIO],
  proactivity: { proactiveAudio: true }
}

Canlı çeviri

Live API, sözlü sohbetlerin gerçek zamanlı ve düşük gecikmeli çevirisini destekler. Bu özellik, anlık sesli çeviri uygulamaları oluşturmanıza olanak tanır.

Daha fazla bilgi ve örnek için Canlı Çeviri kılavuzuna bakın.

Ses Etkinliği Algılama (VAD)

Ses Etkinliği Algılama (VAD), modelin bir kişinin konuştuğu zamanı tanımasını sağlar. Bu, kullanıcının modeli istediği zaman kesmesine olanak tanıdığı için doğal sohbetler oluşturmak açısından önemlidir.

VAD bir kesinti algıladığında devam eden oluşturma işlemi iptal edilir ve silinir. Yalnızca istemciye gönderilmiş olan bilgiler oturum geçmişinde saklanır. Ardından sunucu, kesintiyi bildirmek için BidiGenerateContentServerContent mesajı gönderir.

Gemini sunucusu, bekleyen işlev çağrılarını siler ve iptal edilen çağrıların kimliklerini içeren bir BidiGenerateContentServerContent mesajı gönderir.

Python

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

        # If realtime playback is implemented in your application,
        # you should stop playing audio and clear queued playback here.

JavaScript

const turns = await handleTurn();

for (const turn of turns) {
  if (turn.serverContent && turn.serverContent.interrupted) {
    // The generation was interrupted

    // If realtime playback is implemented in your application,
    // you should stop playing audio and clear queued playback here.
  }
}

Otomatik VAD

Model, varsayılan olarak sürekli bir ses girişi akışında otomatik olarak VAD gerçekleştirir. VAD, kurulum yapılandırmasının realtimeInputConfig.automaticActivityDetection alanı ile 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 sesleri temizlemek için bir audioStreamEnd etkinliği gönderilmelidir. İstemci, ses verilerini göndermeye istediği zaman devam edebilir.

Python

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

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

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

JavaScript

// example audio file to try:
// URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
// !wget -q $URL -O sample.pcm
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  // Send Audio Chunk
  const fileBuffer = fs.readFileSync("sample.pcm");
  const base64Audio = Buffer.from(fileBuffer).toString('base64');

  session.sendRealtimeInput(
    {
      audio: {
        data: base64Audio,
        mimeType: "audio/pcm;rate=16000"
      }
    }

  );

  // if stream gets paused, send:
  // session.sendRealtimeInput({ audioStreamEnd: true })

  const turns = await handleTurn();
  for (const turn of turns) {
    if (turn.text) {
      console.debug('Received text: %s\n', turn.text);
    }
    else if (turn.data) {
      console.debug('Received inline data: %s\n', turn.data);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

send_realtime_input ile API, VAD'ye göre sesli yanıtlara otomatik olarak yanıt verir. send_client_content, iletileri model bağlamına sırayla eklerken send_realtime_input, deterministik sıralama pahasına yanıt verme hızı için optimize edilmiştir.

Otomatik VAD yapılandırması

VAD etkinliği üzerinde daha fazla kontrol sahibi olmak için aşağıdaki parametreleri yapılandırabilirsiniz. Daha fazla bilgi için API referansına bakın.

Python

from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

JavaScript

import { GoogleGenAI, Modality, StartSensitivity, EndSensitivity } from '@google/genai';

const config = {
  responseModalities: [Modality.AUDIO],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: false, // default
      startOfSpeechSensitivity: StartSensitivity.START_SENSITIVITY_LOW,
      endOfSpeechSensitivity: EndSensitivity.END_SENSITIVITY_LOW,
      prefixPaddingMs: 20,
      silenceDurationMs: 100,
    }
  }
};

Hibrit VAD

Karma VAD, otomatik VAD'nin (güçlü konuşma başlangıcı algılama) ve manuel VAD'nin (düşük gecikmeli yanıt tamamlama) avantajlarını birleştirir.

Bu yapılandırmada:

  1. Sunucuda otomatik VAD etkin kalır. Sunucu, kullanıcı konuşmasının başlangıcını otomatik olarak algılar ve ifadelerin başlangıcının kesilmesini önlemek için önek dolgusu kullanır.
  2. İstemci, kullanıcının konuşmayı bıraktığı zamanı algılamak için istemci tarafı VAD kullanır.
  3. İstemci tarafı VAD, konuşmanın sonunu algıladığında sunucuya bir audio_stream_end sinyali gönderir.
  4. Sunucu, audio_stream_end sinyalini anında sonlandırma istemi olarak değerlendirir. Bu sayede, varsayılan sunucu tarafı sessizlik algılama gecikmesi atlanır ve transkript ile model yanıtı minimum gecikmeyle döndürülür.
  5. İstemci tarafı VAD tetiklenmezse sunucu tarafı VAD, konuşmanın sonunu algılamak için yedek olarak kullanılır.

İstemci tarafı VAD eşiğinin çok agresif bir şekilde ayarlanması durumunda konuşma kesintileri yaşanabileceğini unutmayın. Ancak bu yaklaşım, manuel VAD ile oluşabilecek ön kesme sorunlarını önler.

Python

# Set up with automatic VAD enabled (default)
config = {
    "response_modalities": ["AUDIO"],
}

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio data normally
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )

    # When client-side VAD detects the end of speech, send:
    await session.send_realtime_input(audio_stream_end=True)

JavaScript

// Set up with automatic VAD enabled (default)
const config = {
  responseModalities: [Modality.AUDIO],
};

// Send audio data normally
session.sendRealtimeInput({
  audio: {
    data: base64Audio,
    mimeType: "audio/pcm;rate=16000"
  }
});

// When client-side VAD detects the end of speech, send:
session.sendRealtimeInput({ audioStreamEnd: true });

Otomatik VAD'yi devre dışı bırakma

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

Python

config = {
    "response_modalities": ["AUDIO"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

JavaScript

const config = {
  responseModalities: [Modality.AUDIO],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: true,
    }
  }
};

session.sendRealtimeInput({ activityStart: {} })

session.sendRealtimeInput(
  {
    audio: {
      data: base64Audio,
      mimeType: "audio/pcm;rate=16000"
    }
  }

);

session.sendRealtimeInput({ activityEnd: {} })

VAD parametrelerini ve bunların kalite üzerindeki etkisini anlama

Otomatik VAD kullanılırken sesin modele gönderilmeden önce konuşma dönüşlerine nasıl bölüneceğini kontrol eden iki temel parametre vardır:

  • prefixPaddingMs: Konuşma algılanmadan önce eklenecek ses miktarı. Bu "geriye bakma" özelliği, modelin konuşmanın başlangıcını (VAD tetiklenmeden önce başlayabilen ilk hece dahil) tam olarak yakalamasını sağlar. 0 değeri, kelimelerin başlangıcının kırpılmasına neden olabilir.
  • silenceDurationMs: Sunucunun, konuşma sırasını sonlandırmadan önce sessizlik boyunca ne kadar bekleyeceği. Bu değer, sistemin cümle ortasındaki doğal duraksamalara (ör. düşünme, nefes alma veya cümle sınırları) ne kadar toleranslı olduğunu belirler.

silenceDurationMs'nın ses kalitesi üzerindeki etkisi

silenceDurationMs değeri, modelin işleme için aldığı ses parçalarının boyutunu ve eksiksizliğini doğrudan etkiler:

  • Önerilen (500 ms-800 ms): İyi bir denge sağlar. Model, gecikmeyi makul düzeyde tutarken bağlam açısından zengin ve eksiksiz ses parçaları alır. Sunucunun dahili varsayılan değeri yaklaşık 800 ms'dir.
  • Çok düşük (ör. 100 ms-200 ms): Sistem, doğal duraklamalar sırasında konuşma dönüşlerini sonlandırarak tek bir ifadeyi birden fazla küçük ses parçasına böler. Model bu parçaları ayrı ayrı alır. Bu durumda, parçalar arası bağlam kaybolur ve transkripsiyon ile yanıt kalitesi düşer.
  • Çok yüksek (ör.2000 ms+): Sistem, kullanıcı konuşmayı bıraktıktan sonra uzun süre bekler. Bu durum, model yanıt vermeden önce algılanan gecikmeyi artırır.

Manuel (istemci tarafı) VAD ile ilgili en iyi uygulamalar

Otomatik VAD'yi devre dışı bıraktığınızda ve activityStart/activityEnd sinyallerini kendi istemci tarafı ses algılama özelliğinizden yönettiğinizde, sunucunun yerleşik ses arabelleğe alma mekanizmalarının atlandığını unutmayın. Bunun anlamı şudur:

  1. Konuşma öncesi arabellek yok: Sunucu artık algılanan konuşma başlangıcından önce ses eklemiyor. Müşteriniz, activityStart göndermeden önce yeterli ses bağlamı eklemelidir.
  2. Sessizliğe tolerans yok: Sunucu, activityEnd sinyalinize ek bekleme olmadan anında yanıt verir. İstemci tarafındaki VAD'niz agresif bir konuşma sonu eşiği kullanıyorsa (ör. 200 ms sessizlik), konuşma doğal duraklamalar sırasında cümlenin ortasında kesilebilir.

Manuel VAD ile ses kalitesini korumak için, istemcinizin ses aktivite dedektöründe konuşma sonu sessizlik eşiğini en az 500ms olarak kullanın. Bu değerin altındaki eşikler genellikle transkripsiyon ve model yanıt kalitesini düşüren parçalanmış seslere neden olur.

Jeton sayısı

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

Python

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

JavaScript

const turns = await handleTurn();

for (const turn of turns) {
  if (turn.usageMetadata) {
    console.debug('Used %s tokens in total. Response token breakdown:\n', turn.usageMetadata.totalTokenCount);

    for (const detail of turn.usageMetadata.responseTokensDetails) {
      console.debug('%s\n', detail);
    }
  }
}

Medya çözünürlüğü

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

Python

from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "media_resolution": types.MediaResolution.MEDIA_RESOLUTION_LOW,
}

JavaScript

import { GoogleGenAI, Modality, MediaResolution } from '@google/genai';

const config = {
    responseModalities: [Modality.AUDIO],
    mediaResolution: MediaResolution.MEDIA_RESOLUTION_LOW,
};

Sınırlamalar

Projenizi planlarken Canlı API'nin aşağıdaki sınırlamalarını göz önünde bulundurun.

Yanıt biçimleri

Yerel ses modelleri yalnızca "AUDIO" yanıt biçimini destekler. Model yanıtını metin olarak almak istiyorsanız çıkış sesini metne dönüştürme özelliğini kullanın.

İstemci kimlik doğrulaması

Live API, varsayılan olarak yalnızca sunucudan sunucuya kimlik doğrulama sağlar. Live API uygulamanızı istemciden sunucuya yaklaşımı kullanarak uyguluyorsanız güvenlik risklerini azaltmak için geçici jetonlar kullanmanız gerekir.

Oturum süresi

Yalnızca sesli oturumlar 15 dakika, sesli ve görüntülü oturumlar ise 2 dakika ile sınırlıdır. Ancak oturum süresinin sınırsız uzatılması için farklı oturum yönetimi teknikleri yapılandırabilirsiniz.

Bağlam penceresi

Bir oturumun bağlam penceresi sınırı şöyledir:

Desteklenen diller

Live API aşağıdaki 97 dili destekler.

Dil BCP-47 kodu Dil BCP-47 kodu
Afrikaanca af Letonca lv
Akan ak Litvanca lt
Arnavutça sq Makedonca mk
Amharca am Malayca ms
Arapça ar Malayalamca ml
Ermenice hy Maltaca mt
Assamca as Maori mi
Azerice az Marathi mr
Baskça eu Moğolca mn
Belarusça be Nepalce ne
Bengalce bn Norveççe no
Boşnakça bs Oriya or
Bulgarca bg Oromca om
Burmaca my Peştuca ps
Katalanca ca Farsça fa
Sabuanca ceb Lehçe pl
Çince zh Portekizce pt
Hırvatça hr Pencapça pa
Çekya cs Keçuva dili qu
Danca da Rumence ro
Felemenkçe nl Romanşça rm
İngilizce en Rusça ru
Estonca et Sırpça sr
Faroese fo Sindice sd
Filipince fil Seylanca si
Fince fi Slovakça sk
Fransızca fr Slovence sl
Galiçyaca gl Somalice so
Gürcüce ka Güney Sotho dili st
Almanca de İspanyolca es
Greek el Swahili sw
Güceratça gu İsveççe sv
Hausaca ha Tacikçe tg
İbranice iw Tamilce ta
Hintçe hi Telugu dili te
Macarca hu Tayca th
İzlandaca is Tsvana tn
Endonezce id Türkçe tr
İrlandaca ga Türkmence tk
İtalyanca it Ukraynaca uk
Japonca ja Urduca ur
Kannada kn Özbekçe uz
Kazakça kk Vietnamca vi
Kmerce km Galce cy
Ruandaca rw Batı Frizcesi fy
Korece ko Wolof dili wo
Kürtçe ku Yorubaca yo
Kırgızca ky Zulu zu
Laoca lo

Sırada ne var?