Udhëzues për aftësitë e API-t Live

Ky është një udhëzues gjithëpërfshirës që mbulon aftësitë dhe konfigurimet e disponueshme me Live API. Shihni faqen "Filloni me Live API" për një përmbledhje dhe kod shembull për rastet e përdorimit të zakonshëm.

Para se të filloni

  • Njihuni me konceptet kryesore: Nëse nuk e keni bërë ende, lexoni më parë faqen "Filloni me Live API" . Kjo do t'ju prezantojë me parimet themelore të Live API, mënyrën e funksionimit të tij dhe qasjet e ndryshme të zbatimit .
  • Provoni API-n Live në AI Studio: Mund ta gjeni të dobishme të provoni API-n Live në Google AI Studio përpara se të filloni ndërtimin. Për të përdorur API-n Live në Google AI Studio, zgjidhni Transmetim .

Krahasimi i modelit

Tabela e mëposhtme përmbledh ndryshimet kryesore midis modeleve Gemini 3.1 Flash Live Preview dhe Gemini 2.5 Flash Live Preview :

Karakteristikë Pamje paraprake e drejtpërdrejtë e Gemini 3.1 Flash Pamje paraprake e drejtpërdrejtë e Gemini 2.5 Flash
Të menduarit Përdor thinkingLevel për të kontrolluar thellësinë e të menduarit me cilësime si minimal , low , medium dhe high . Parazgjedhja është minimal për të optimizuar për vonesën më të ulët. Shihni Nivelet dhe buxhetet e të menduarit . Përdor thinkingBudget për të vendosur numrin e tokenëve të të menduarit. Të menduarit dinamik është aktivizuar si parazgjedhje. Vendoseni thinkingBudget në 0 për ta çaktivizuar. Shihni Nivelet dhe buxhetet e të menduarit .
Marrja e përgjigjes Një ngjarje e vetme serveri mund të përmbajë disa pjesë përmbajtjeje njëkohësisht (për shembull, inlineData dhe transkript). Sigurohuni që kodi juaj të përpunojë të gjitha pjesët në secilën ngjarje për të shmangur mungesën e përmbajtjes. Çdo ngjarje e serverit përmban vetëm një pjesë përmbajtjeje. Pjesët dorëzohen në ngjarje të ndara.
Përmbajtja e klientit send_client_content mbështetet vetëm për mbjelljen e historikut të kontekstit fillestar (kërkon vendosjen e initial_history_in_client_content në konfigurimin e sesionit). Për të dërguar përditësime me tekst gjatë bisedës, përdorni në vend të send_realtime_input . send_client_content mbështetet gjatë gjithë bisedës për dërgimin e përditësimeve graduale të përmbajtjes dhe krijimin e kontekstit.
Mbulimi i kthesës Parazgjedhur në TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO . Radha e modelit përfshin aktivitetin audio të zbuluar dhe të gjitha kuadrot video. Parazgjedhur në TURN_INCLUDES_ONLY_ACTIVITY . Radha e modelit përfshin vetëm aktivitetin e zbuluar.
VAD i personalizuar ( activity_start / activity_end ) Mbështetet . Çaktivizo VAD-in automatik dhe dërgo manualisht mesazhet activityStart dhe activityEnd për të kontrolluar kufijtë e kthesës. Mbështetet . Çaktivizo VAD-in automatik dhe dërgo manualisht mesazhet activityStart dhe activityEnd për të kontrolluar kufijtë e kthesës.
Konfigurimi automatik i VAD-it Mbështetet . Konfiguroni parametra të tillë si start_of_speech_sensitivity , end_of_speech_sensitivity , prefix_padding_ms dhe silence_duration_ms . Mbështetet . Konfiguroni parametra të tillë si start_of_speech_sensitivity , end_of_speech_sensitivity , prefix_padding_ms dhe silence_duration_ms .
Thirrja e funksionit asinkron ( behavior: NON_BLOCKING ) Nuk mbështetet . Thirrja e funksionit është vetëm sekuenciale. Modeli nuk do të fillojë të përgjigjet derisa të keni dërguar përgjigjen e mjetit. Mbështetet . Vendos behavior në NON_BLOCKING në një deklaratë funksioni për të lejuar modelin të vazhdojë të bashkëveprojë ndërsa funksioni ekzekutohet. Kontrolloni se si modeli i trajton përgjigjet me parametrin scheduling ( INTERRUPT , WHEN_IDLE ose SILENT ).
Audio proaktive Nuk mbështetet Mbështetur . Kur aktivizohet, modeli mund të vendosë në mënyrë proaktive të mos përgjigjet nëse përmbajtja e hyrjes nuk është relevante. Vendos proactive_audio në true në konfigurimin proactivity (kërkon v1alpha ).
Dialog afektiv Nuk mbështetet Mbështetur . Modeli e përshtat stilin e tij të përgjigjes për t'u përputhur me shprehjen dhe tonin e të dhënave hyrëse. Vendos enable_affective_dialog në true në konfigurimin e sesionit (kërkon v1alpha ).

Për të migruar nga Gemini 2.5 Flash Live në Gemini 3.1 Flash Live, shihni udhëzuesin e migrimit .

Vendosja e një lidhjeje

Shembulli i mëposhtëm tregon se si të krijoni një lidhje me një çelës API:

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

Modalitetet e ndërveprimit

Seksionet e mëposhtme ofrojnë shembuj dhe kontekst mbështetës për modalitetet e ndryshme të hyrjes dhe daljes të disponueshme në Live API.

Duke dërguar audion

Audio duhet të dërgohet si të dhëna të papërpunuara PCM (audio PCM 16-bit i papërpunuar, 16kHz, little-endian).

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

Formatet audio

Të dhënat audio në Live API janë gjithmonë të papërpunuara, little-endian, PCM 16-bit. Dalja audio përdor gjithmonë një shpejtësi mostrimi prej 24kHz. Audio hyrëse është natyrshëm 16kHz, por Live API do të rimodelojë nëse është e nevojshme, në mënyrë që të mund të dërgohet çdo shpejtësi mostrimi. Për të përcjellë shpejtësinë e mostrimit të audios hyrëse, vendosni llojin MIME të çdo Blob që përmban audio në një vlerë si audio/pcm;rate=16000 .

Po merr audion

Përgjigjet audio të modelit merren si pjesë të të dhënave.

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

Duke dërguar mesazh

Teksti mund të dërgohet duke përdorur send_realtime_input (Python) ose sendRealtimeInput (JavaScript).

Python 

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

JavaScript 

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

Duke dërguar videon

Kornizat video dërgohen si imazhe individuale (p.sh., JPEG ose PNG) me një shpejtësi specifike të kuadrove (maksimumi 1 kornizë për sekondë).

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

Përditësime shtesë të përmbajtjes

Përdorni përditësime graduale për të dërguar tekst, për të krijuar kontekstin e sesionit ose për të rivendosur kontekstin e sesionit. Për kontekste të shkurtra, mund të dërgoni ndërveprime hap pas hapi për të përfaqësuar sekuencën e saktë të ngjarjeve:

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

Për kontekste më të gjata, rekomandohet të jepni një përmbledhje të vetme mesazhi për të liruar dritaren e kontekstit për ndërveprimet pasuese. Shihni Rifillimin e Sesionit për një metodë tjetër për ngarkimin e kontekstit të sesionit.

Transkriptime audio

Përveç përgjigjes së modelit, mund të merrni edhe transkriptime si të daljes audio ashtu edhe të hyrjes audio.

Për të aktivizuar transkriptimin e daljes audio të modelit, dërgoni output_audio_transcription në konfigurimin e konfigurimit. Gjuha e transkriptimit nxirret nga përgjigja e modelit.

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

Për të aktivizuar transkriptimin e të dhënave audio të modelit, dërgoni input_audio_transcription në konfigurimin e konfigurimit.

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

Ndrysho zërin dhe gjuhën

Modelet e daljes audio vendase mbështesin çdo zë të disponueshëm për modelet tona Tekst-në-Fjalë (TTS) . Ju mund t'i dëgjoni të gjithë zërat në AI Studio .

Për të specifikuar një zë, vendosni emrin e zërit brenda objektit speechConfig si pjesë e konfigurimit të sesionit:

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

API-ja Live mbështet shumë gjuhë . Modelet e daljes audio vendase zgjedhin automatikisht gjuhën e duhur dhe nuk mbështesin caktimin e qartë të kodit të gjuhës.

Aftësi audio vendase

Modelet tona më të fundit kanë dalje audio native , e cila ofron të folur natyrale dhe realiste dhe performancë të përmirësuar shumëgjuhëshe.

Të menduarit

Modelet Gemini 3.1 përdorin thinkingLevel për të kontrolluar thellësinë e të menduarit, me cilësime si minimal , low , medium dhe high . Vlera parazgjedhur është minimal për të optimizuar për vonesën më të ulët. Modelet Gemini 2.5 përdorin thinkingBudget për të vendosur numrin e tokenëve të të menduarit. Për më shumë detaje mbi nivelet kundrejt buxheteve, shihni Nivelet dhe buxhetet e të menduarit .

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

Për më tepër, mund të aktivizoni përmbledhjet e mendimeve duke vendosur includeThoughts në true në konfigurimin tuaj. Shihni përmbledhjet e mendimeve për më shumë informacion:

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

Dialog afektiv

Kjo veçori i lejon Gemini-t të përshtasë stilin e tij të përgjigjes sipas shprehjes dhe tonit të hyrjes.

Për të përdorur dialogun affective, caktoni versionin api në v1alpha dhe caktoni enable_affective_dialog në true në mesazhin e konfigurimit:

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

Audio proaktive

Kur kjo veçori është e aktivizuar, Gemini mund të vendosë në mënyrë proaktive të mos përgjigjet nëse përmbajtja nuk është relevante.

Për ta përdorur, caktoni versionin api në v1alpha dhe konfiguroni fushën e proactivity në mesazhin e konfigurimit dhe caktoni proactive_audio në true :

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

Zbulimi i Aktivitetit të Zërit (VAD)

Zbulimi i Aktivitetit të Zërit (VAD) i lejon modelit të njohë kur një person po flet. Kjo është thelbësore për krijimin e bisedave natyrale, pasi i lejon një përdoruesi ta ndërpresë modelin në çdo kohë.

Kur VAD zbulon një ndërprerje, gjenerimi në vazhdim anulohet dhe hidhet poshtë. Vetëm informacioni që i është dërguar tashmë klientit ruhet në historikun e seancës. Serveri më pas dërgon një mesazh BidiGenerateContentServerContent për të raportuar ndërprerjen.

Serveri Gemini më pas hedh poshtë çdo thirrje funksioni në pritje dhe dërgon një mesazh BidiGenerateContentServerContent me ID-të e thirrjeve të anuluara.

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

VAD automatik

Si parazgjedhje, modeli kryen automatikisht VAD në një rrjedhë të vazhdueshme hyrëse audio. VAD mund të konfigurohet me fushën realtimeInputConfig.automaticActivityDetection të konfigurimit të konfigurimit .

Kur transmetimi audio ndalet për më shumë se një sekondë (për shembull, sepse përdoruesi e ka fikur mikrofonin), duhet të dërgohet një ngjarje audioStreamEnd për të pastruar çdo audio të ruajtur në memorien e përkohshme. Klienti mund të rifillojë dërgimin e të dhënave audio në çdo kohë.

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

Me send_realtime_input , API do t'i përgjigjet audios automatikisht bazuar në VAD. Ndërsa send_client_content shton mesazhe në kontekstin e modelit sipas radhës, send_realtime_input është optimizuar për reagim në kurriz të renditjes deterministike.

Konfigurimi automatik i VAD-it

Për më shumë kontroll mbi aktivitetin VAD, mund të konfiguroni parametrat e mëposhtëm. Shihni referencën API për më shumë informacion.

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

Çaktivizo VAD-in automatik

Si alternativë, VAD automatik mund të çaktivizohet duke vendosur realtimeInputConfig.automaticActivityDetection.disabled në true në mesazhin e konfigurimit. Në këtë konfigurim, klienti është përgjegjës për zbulimin e të folurit të përdoruesit dhe dërgimin e mesazheve activityStart dhe activityEnd në kohën e duhur. Një audioStreamEnd nuk dërgohet në këtë konfigurim. Në vend të kësaj, çdo ndërprerje e transmetimit shënohet nga një mesazh activityEnd .

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: {} })

Kuptimi i parametrave VAD dhe ndikimi i tyre në cilësi

Kur përdoret VAD automatike, dy parametra kryesorë kontrollojnë se si ndahet audioja në kthesa të të folurit përpara se të dërgohet në model:

  • prefixPaddingMs : Sasia e audios që duhet të përfshihet përpara se të zbulohet të folurit. Ky "vështrim prapa" siguron që modeli të kapë fillimin e plotë të të folurit, duke përfshirë rrokjen e parë që mund të fillojë përpara se të aktivizohet VAD. Një vlerë prej 0 mund të shkaktojë prerjen e fillimit të fjalëve.
  • silenceDurationMs : Sa kohë pret serveri gjatë heshtjes përpara se të përfundojë një raund të të folurit. Kjo përcakton se sa tolerant është sistemi ndaj pauzave natyrore në mes të fjalive (p.sh., të menduarit, frymëmarrja ose kufijtë e fjalive).

Ndikimi i silenceDurationMs në cilësinë e audios

Vlera silenceDurationMs ndikon drejtpërdrejt në madhësinë dhe plotësinë e pjesëve audio që modeli merr për përpunim:

  • I rekomanduar (500ms–800ms): Ofron një ekuilibër të mirë—modeli merr pjesë audio të plota dhe të pasura me kontekst, duke e mbajtur vonesën të arsyeshme. Parazgjedhja e brendshme e serverit është afërsisht 800ms.
  • Shumë e ulët (p.sh., 100ms–200ms): Sistemi i ndërpret kthesat e të folurit gjatë pauzave natyrore, duke e ndarë një shprehje të vetme në disa fragmente të vogla audio. Modeli i merr këto fragmente individualisht, duke humbur kontekstin e fragmenteve të kryqëzuara dhe duke rezultuar në transkriptim dhe cilësi më të ulët të përgjigjes.
  • Shumë e lartë (p.sh., 2000ms+): Sistemi pret një kohë të gjatë pasi përdoruesi ndalon së foluri, duke rritur vonesën e perceptuar përpara se modeli të përgjigjet.

Praktikat më të mira për VAD manual (nga ana e klientit)

Kur çaktivizoni VAD-in automatik dhe menaxhoni sinjalet activityStart / activityEnd nga zbulimi i zërit në anën e klientit, kini parasysh se mekanizmat e integruar të bufferimit audio të serverit anashkalohen. Kjo do të thotë:

  1. Pa memorje paraprake për të folurit: Serveri nuk e përgatit më audion para fillimit të të folurit të zbuluar. Klienti juaj duhet të përfshijë kontekst të mjaftueshëm audio përpara se të dërgojë activityStart .
  2. Pa tolerancë ndaj heshtjes: Serveri vepron menjëherë sipas sinjalit tuaj activityEnd pa asnjë pritje shtesë. Nëse VAD-i juaj në anën e klientit përdor një prag agresiv të mbarimit të të folurit (p.sh., 200ms heshtje), të folurit mund të ndërpritet në mes të fjalisë gjatë pauzave natyrore.

Për të ruajtur cilësinë e audios me VAD manual, përdorni një prag heshtjeje në fund të të folurit prej të paktën 500ms në detektorin e aktivitetit zanor të klientit tuaj. Pragjet nën këtë vlerë shpesh shkaktojnë audio të fragmentuar që degradon cilësinë e transkriptimit dhe të përgjigjes së modelit.

Numri i tokenëve

Mund ta gjeni numrin total të tokenëve të konsumuar në fushën usageMetadata të mesazhit të kthyer të serverit.

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

Rezolucioni i medias

Mund të specifikoni rezolucionin e medias për median hyrëse duke vendosur fushën mediaResolution si pjesë të konfigurimit të sesionit:

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

Kufizime

Merrni parasysh kufizimet e mëposhtme të Live API kur planifikoni projektin tuaj.

Modalitetet e reagimit

Modelet audio vendase mbështesin vetëm modalitetin e përgjigjes `AUDIO. Nëse ju nevojitet përgjigja e modelit si tekst, përdorni veçorinë e transkriptimit të audios së daljes .

Autentifikimi i klientit

API-ja Live ofron vetëm autentifikim server-me-server si parazgjedhje. Nëse po e implementoni aplikacionin tuaj Live API duke përdorur një qasje klient-me-server , duhet të përdorni tokena kalimtarë për të zbutur rreziqet e sigurisë.

Kohëzgjatja e seancës

Sesionet vetëm me audio janë të kufizuara në 15 minuta, dhe sesionet me audio plus video janë të kufizuara në 2 minuta. Megjithatë, mund të konfiguroni teknika të ndryshme të menaxhimit të sesionit për zgjatje të pakufizuara të kohëzgjatjes së sesionit.

Dritarja e kontekstit

Një seancë ka një limit të dritares së kontekstit prej:

Gjuhët e mbështetura

Live API mbështet 97 gjuhët e mëposhtme.

Gjuha Kodi BCP-47 Gjuha Kodi BCP-47
Afrikanisht af letonisht lv
Akan ak lituanisht lt
shqip sq maqedonase mk
Amarike am Malajisht ms
Arabisht ar Malajalamisht ml
armenisht hy maltezisht mt
Asamezisht as Maori mi
Azerbajxhanisht az Marathi mr
bask eu mongolisht mn
Bjellorusisht be Nepalisht ne
Bengalisht bn Norvegjisht no
boshnjak bs Odia or
bullgar bg Oromo om
birmanisht my Pashto ps
Katalanisht ca persisht fa
Cebuanisht ceb polak pl
kinez zh portugalisht pt
Kroatisht hr Punjabi pa
Çeke cs Keçua qu
danez da rumanisht ro
holandez nl Romansh rm
Anglisht en ruse ru
Estonisht et serbisht sr
Faroisht fo Sindhi sd
Filipinase fil Sinhalisht si
finlandez fi Sllovakisht sk
frëngjisht fr sllovenisht sl
galike gl somalisht so
gjeorgjian ka Sotho Jugore st
gjermanisht de Spanjisht es
grek el Suahili sw
Guxharatisht gu suedeze sv
Hausisht ha Taxhikisht tg
Hebraisht iw Tamil ta
Hindisht hi Teluguisht te
hungareze hu Tajlandeze th
Islandeze is Tsvana tn
Indonezisht id turk tr
irlandez ga Turkmen tk
italiane it ukrainas uk
Japonez ja Urdu ur
Kannada kn Uzbekisht uz
Kazake kk Vietnamez vi
Khmer km Uellsisht cy
Kinyarwanda rw friziane perëndimore fy
Koreane ko Wolofisht wo
Kurd ku Joruba yo
kirgizisht ky Zulu zu
Lao lo

Çfarë vjen më pas