2.5 düşünen model ailemizdeki güncellemeleri kullanıma sunuyoruz. Daha fazla bilgi

Bu sayfa, Cloud Translation API ile çevrilmiştir.

Live API capabilities guide

Bu, Canlı API'de kullanılabilen özellikleri ve yapılandırmaları kapsayan kapsamlı bir kılavuzdur. Yaygın kullanım alanlarına genel bakış ve örnek kod için Live API'yi kullanmaya başlama sayfasına bakın.

Başlamadan önce

Temel kavramlarla tanışın: Henüz yapmadıysanız önce Live API'yi kullanmaya başlama sayfasını okuyun. Bu eğitimde, Live API'nin temel ilkeleri, işleyiş şekli ve farklı modeller ile bunlara karşılık gelen ses oluşturma yöntemleri (yerel ses veya yarı basamaklı) arasındaki farklar açıklanmaktadır.
AI Studio'da Canlı API'yi deneyin: Uygulama 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 Yayın'ı seçin.

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-live-2.5-flash-preview"
config = {"response_modalities": ["TEXT"]}

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

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

JavaScript

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

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

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,
  });

  // Send content...

  session.close();
}

main();

Etkileşim modları

Aşağıdaki bölümlerde, Live API'de kullanılabilen farklı giriş ve çıkış modları için örnekler ve destekleyici bağlam sağlanmaktadır.

Metin gönderme ve alma

Metin mesajı gönderip alabilmek için:

Python

import asyncio
from google import genai

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

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello, how are you?"
        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())

JavaScript

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

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

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

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:

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 bağlamlarda, sonraki etkileşimler için bağlam penceresini boşaltmak amacıyla tek bir mesaj özeti sağlamanız önerilir. Oturum bağlamını yüklemeyle ilgili başka bir yöntem için Oturum Devam Ettirme başlıklı makaleyi inceleyin.

Ses gönderme ve alma

En yaygın ses örneği olan ses-sese, Başlangıç kılavuzunda ele alınmıştır.

Aşağıda, bir WAV dosyasını okuyan, doğru biçimde gönderen ve metin çıkışı alan bir ses metne dönüştürme örneği verilmiştir:

Python

# Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav
# Install helpers for converting files: pip install librosa soundfile
import asyncio
import io
from pathlib import Path
from google import genai
from google.genai import types
import soundfile as sf
import librosa

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

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:

        buffer = io.BytesIO()
        y, sr = librosa.load("sample.wav", sr=16000)
        sf.write(buffer, y, sr, format='RAW', subtype='PCM_16')
        buffer.seek(0)
        audio_bytes = buffer.read()

        # If already in correct format, you can use this:
        # audio_bytes = Path("sample.pcm").read_bytes()

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

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

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

JavaScript

// Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav
// Install helpers for converting files: npm install wavefile
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-live-2.5-flash-preview';
const config = { responseModalities: [Modality.TEXT] };

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.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);
    }
  }

  session.close();
}

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

main();

Aşağıda metinden sese dönüştürme örneği verilmiştir. Yanıt modu olarak AUDIO'ü ayarlayarak ses alabilirsiniz. Bu örnekte, alınan veriler WAV dosyası olarak kaydedilir:

Python

import asyncio
import wave
from google import genai

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

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 how are you?"
        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in 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())

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-live-2.5-flash-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,
  });

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

  const turns = await handleTurn();

  // Combine audio data strings and save as wave file
  const combinedAudio = turns.reduce((acc, turn) => {
    if (turn.data) {
      const buffer = Buffer.from(turn.data, 'base64');
      const intArray = new Int16Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / Int16Array.BYTES_PER_ELEMENT);
      return acc.concat(Array.from(intArray));
    }
    return acc;
  }, []);

  const audioBuffer = new Int16Array(combinedAudio);

  const wf = new WaveFile();
  wf.fromScratch(1, 24000, '16', audioBuffer);
  fs.writeFileSync('output.wav', wf.toBuffer());

  session.close();
}

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

main();

Ses biçimleri

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

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

Kurulum yapılandırmasında output_audio_transcription göndererek modelin ses çıkışının metne dönüştürülmesini etkinleştirebilirsiniz. Metne dönüştürme dili, modelin yanıtından anlaşılır.

Python

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

client = genai.Client()
model = "gemini-live-2.5-flash-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-live-2.5-flash-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();

Kurulum yapılandırmasında input_audio_transcription göndererek ses girişinin transkriptini etkinleştirebilirsiniz.

Python

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

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

config = {
    "response_modalities": ["TEXT"],
    "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-live-2.5-flash-preview';

const config = {
  responseModalities: [Modality.TEXT],
  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.serverContent && turn.serverContent.outputTranscription) {
      console.log("Transcription")
      console.log(turn.serverContent.outputTranscription.text);
    }
  }
  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 ve video aktarma

Ses ve dili değiştirme

Live API modellerinin her biri farklı bir ses grubunu destekler. Yarım şelale; Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus ve Zephyr'i destekler. Yerel ses, çok daha uzun bir listeyi destekler (TTS model listesine benzer). Tüm sesleri AI Studio'da dinleyebilirsiniz.

Ses belirtmek için oturum yapılandırmasının bir parçası olarak speechConfig nesnesinde 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.

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

Python

config = {
    "response_modalities": ["AUDIO"],
    "speech_config": {
        "language_code": "de-DE"
    }
}

JavaScript

const config = {
  responseModalities: [Modality.AUDIO],
  speechConfig: { languageCode: "de-DE" }
};

Yerel ses özellikleri

Aşağıdaki özellikler yalnızca yerel sesle kullanılabilir. Model ve ses oluşturma seçin başlıklı makalede doğal ses hakkında daha fazla bilgi edinebilirsiniz.

Yerel ses çıkışını kullanma

Yerel ses çıkışını kullanmak için yerel ses modellerinden birini yapılandırın ve response_modalities değerini AUDIO olarak ayarlayın.

Tam bir örnek için Ses gönderme ve alma bölümüne bakın.

Python

model = "gemini-2.5-flash-preview-native-audio-dialog"
config = types.LiveConnectConfig(response_modalities=["AUDIO"])

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

JavaScript

const model = 'gemini-2.5-flash-preview-native-audio-dialog';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

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

  // Send audio input and receive audio

  session.close();
}

main();

Duygusal diyalog

Bu özellik, Gemini'nin yanıt tarzını giriş ifadesine ve üslubuna uyarlamasını sağlar.

Duygusal diyalog kullanmak için API sürümünü v1alpha olarak, kurulum mesajında enable_affective_dialog değerini true olarak ayarlayın:

Python

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

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

JavaScript

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

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

Duygusal diyaloğun şu anda yalnızca yerel ses çıkışı modelleri tarafından desteklendiğini unutmayın.

Proaktif ses

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

Bunu kullanmak için api sürümünü v1alpha olarak ayarlayın ve kurulum mesajındaki proactivity alanını yapılandırın ve proactive_audio değerini true olarak ayarlayın:

Python

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

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

JavaScript

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

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

Proaktif sesin şu anda yalnızca yerel ses çıkışı modelleri tarafından desteklendiğini unutmayın.

Düşünmeyle birlikte doğal ses çıkışı

Yerel ses çıkışı, ayrı bir model gemini-2.5-flash-exp-native-audio-thinking-dialog aracılığıyla kullanılabilen düşünme özelliklerini destekler.

Tam bir örnek için Ses gönderme ve alma bölümüne bakın.

Python

model = "gemini-2.5-flash-exp-native-audio-thinking-dialog"
config = types.LiveConnectConfig(response_modalities=["AUDIO"])

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

JavaScript

const model = 'gemini-2.5-flash-exp-native-audio-thinking-dialog';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

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

  // Send audio input and receive audio

  session.close();
}

main();

Konuşma Etkinliği Algılama (VAD)

Ses Aktivitesi Algılama (VAD), modelin bir kişinin konuştuğunu tanımasına olanak tanır. Kullanıcının modeli istediği zaman kesintiye uğratmasına olanak tanıdığı için bu, doğal sohbetler oluşturmak için gereklidir.

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.

Gemini sunucusu, bekleyen tüm 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ı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.

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-live-2.5-flash-preview"

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

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-live-2.5-flash-preview';
const config = { responseModalities: [Modality.TEXT] };

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, seslere VAD'ye göre otomatik olarak yanıt verir. send_client_content, model içeriğine sırayla mesaj eklerken send_realtime_input, belirli bir sırayla sıralama pahasına yanıt verebilirlik için optimize edilir.

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": ["TEXT"],
    "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.TEXT],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: false, // default
      startOfSpeechSensitivity: StartSensitivity.START_SENSITIVITY_LOW,
      endOfSpeechSensitivity: EndSensitivity.END_SENSITIVITY_LOW,
      prefixPaddingMs: 20,
      silenceDurationMs: 100,
    }
  }
};

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

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.

Python

config = {
    "response_modalities": ["TEXT"],
    "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.TEXT],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: true,
    }
  }
};

session.sendRealtimeInput({ activityStart: {} })

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

);

session.sendRealtimeInput({ activityEnd: {} })

Jeton sayısı

Kullanılan 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.TEXT],
    mediaResolution: MediaResolution.MEDIA_RESOLUTION_LOW,
};

Sınırlamalar

Projenizi planlarken Live API'nin aşağıdaki sınırlamalarına dikkat edin.

Yanıt modları

Oturum yapılandırmasında oturum başına yalnızca bir yanıt modu (TEXT veya AUDIO) ayarlayabilirsiniz. Her iki ayarı da ayarlamak, 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ı

Canlı API varsayılan olarak yalnızca sunucudan sunucuya kimlik doğrulaması sağlar. Canlı API uygulamanızı istemci-sunucu yaklaşımını 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üresini sınırsız olarak uzatmak için farklı oturum yönetimi teknikleri yapılandırabilirsiniz.

Bağlam penceresi

Oturumların bağlam penceresi sınırı şunlardır:

Yerel ses çıkışı modelleri için 128.000 jeton
Diğer Canlı API modelleri için 32 bin jeton

Desteklenen diller

Live API aşağıdaki dilleri destekler.

Dil	BCP-47 Kodu	Dil	BCP-47 Kodu
Almanca (Almanya)	`de-DE`	İngilizce (Avustralya)*	`en-AU`
İngilizce (İngiltere)*	`en-GB`	İngilizce (Hindistan)	`en-IN`
İngilizce (ABD)	`en-US`	İspanyolca (ABD)	`es-US`
Fransızca (Fransa)	`fr-FR`	Hintçe (Hindistan)	`hi-IN`
Portekizce (Brezilya)	`pt-BR`	Arapça (Genel)	`ar-XA`
İspanyolca (İspanya)*	`es-ES`	Fransızca (Kanada)*	`fr-CA`
Endonezce (Endonezya)	`id-ID`	İtalyanca (İtalya)	`it-IT`
Japonca (Japonya)	`ja-JP`	Türkçe (Türkiye)	`tr-TR`
Vietnamca (Vietnam)	`vi-VN`	Bengalce (Hindistan)	`bn-IN`
Guceratça (Hindistan)*	`gu-IN`	Kannada dili (Hindistan)*	`kn-IN`
Marathice (Hindistan)	`mr-IN`	Malayalamca (Hindistan)*	`ml-IN`
Tamilce (Hindistan)	`ta-IN`	Telugu dili (Hindistan)	`te-IN`
Felemenkçe (Hollanda)	`nl-NL`	Korece (Güney Kore)	`ko-KR`
Çince (Mandarin) (Çin)*	`cmn-CN`	Lehçe (Polonya)	`pl-PL`
Rusça (Rusya)	`ru-RU`	Tay Dili (Tayland)	`th-TH`

Yıldız işareti (*) ile işaretlenen diller doğal ses için kullanılamaz.

Sırada ne var?

Live API'yi etkili bir şekilde kullanma hakkında temel bilgiler için Araç Kullanımı ve Oturum Yönetimi kılavuzlarını okuyun.
Google AI Studio'da Live API'yi deneyin.
Live API modelleri hakkında daha fazla bilgi için Modeller sayfasındaki Gemini 2.0 Flash Live ve Gemini 2.5 Flash Native Audio başlıklı makalelere bakın.
Live API yemek kitabındaki, Live API Araçları yemek kitabındaki ve Live API'yi kullanmaya başlama komut dosyasındaki diğer örnekleri deneyin.