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.8 Live , Gemini 3.8 Live Extended Thinking dhe Gemini 3.1 Flash Live Preview :

Karakteristikë Binjakët 3.8 Live Binjakët 3.8 Jeto Mendimin e Zgjeruar Pamje paraprake e drejtpërdrejtë e Gemini 3.1 Flash
Rekomandohet për Opsioni parazgjedhur për shumicën e përvojave të agjentit zanor me vonesë të ulët. Rekomandohet kur kërkohet arsyetim më i thellë në sfond. Modeli i vjetër i parapamjes. Ne rekomandojmë përditësimin në Gemini 3.8 Live .
Të menduarit Mbështetet (arsyetim i ndërthurur). thinkingLevel nuk mbështetet (hiqe nga konfigurimi). Mbështetet . Arsyetim i sfondit i konfigurueshëm ( thinkingLevel : low , medium , high ; minimal nuk mbështetet). 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. Shih Thinking në Live API .
Marrja e përgjigjes Një ngjarje e vetme e serverit mund të përmbajë pjesë të shumta përmbajtjeje njëkohësisht. Një ngjarje e vetme serveri mund të përmbajë pjesë të shumta përmbajtjeje njëkohësisht. Kur arsyetimi asinkron është aktiv, turnComplete: true nuk tregon një seancë joaktive; përdorni interaction_status ( IN_PROGRESS kundrejt IDLE ). 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.
Përmbajtja e klientit send_client_content mbështetet gjatë gjithë ciklit jetësor të sesionit me role të qarta ( user ose model ). turn_complete=true ndërpret pa kushte gjenerimin. send_client_content mbështetet gjatë gjithë ciklit jetësor të sesionit me role të qarta ( user ose model ). turn_complete=true ndërpret pa kushte gjenerimin. send_client_content mbështetet gjatë gjithë ciklit jetësor të sesionit me role të qarta ( user ose model ). turn_complete=true ndërpret pa kushte gjenerimin.
Thirrja e funksionit asinkron ( behavior: NON_BLOCKING ) Mbështetet (parazgjedhur). Cakto behavior: NON_BLOCKING ose përdor modalitetin e bllokimit të pajtueshëm me prapa me behavior: BLOCKING . Planifikimi i funksioneve ( SILENT , WHEN_IDLE , INTERRUPTED ) mbështetet. Mbështetet (Vetëm Asinkron). Mbështetet vetëm ekzekutimi NON_BLOCKING . Modaliteti i bllokimit dhe planifikimi i funksionit nuk mbështeten. 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.

Për të migruar në Gemini 3.8 Live, shihni udhëzuesin e migrimit . Për të mësuar më shumë rreth Thinking, shihni udhëzuesin Thinking dhe udhëzuesin e përmirësimit .

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.8-live"
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.8-live';
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.8-live"

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.8-live';

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.8-live"

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.8-live';

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.8 Live Extended Thinking dhe Gemini 3.1 përdorin thinkingLevel për të kontrolluar thellësinë e të menduarit. Për gemini-3.8-live , thinkingLevel nuk mbështetet dhe duhet të hiqet në konfigurim. Gemini 3.8 Live Extended Thinking mbështet low , medium dhe high (nuk mbështetet minimal ). Modelet Gemini 3.1 mbështesin minimal , low , medium dhe high . Për më shumë detaje, shihni Thinking in the Live API .

Python 

model = "gemini-3.8-live-extended-thinking"

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.8-live-extended-thinking';
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.8-live-extended-thinking"

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

JavaScript 

const model = 'gemini-3.8-live-extended-thinking';
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ë v1beta dhe caktoni enable_affective_dialog në true në mesazhin e konfigurimit:

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

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, vendosni versionin api në v1beta dhe konfiguroni fushën e proactivity në mesazhin e konfigurimit dhe vendosni proactive_audio në true :

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

Përkthim i drejtpërdrejtë

API-ja Live mbështet përkthimin në kohë reale dhe me vonesë të ulët të bisedave të folura. Kjo aftësi ju lejon të ndërtoni aplikacione përkthimi zë-në-zë në kohë reale.

Për më shumë informacion dhe shembuj, shihni udhëzuesin e Përkthimit të Drejtpërdrejtë .

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.8-live"

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.8-live';
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,
    }
  }
};

VAD hibrid

VAD hibrid kombinon përfitimet e VAD automatike (zbulimi i fuqishëm i fillimit të të folurit) dhe VAD manuale (finalizimi i përgjigjes me vonesë të ulët).

Në këtë konfigurim:

  1. VAD automatik mbetet i aktivizuar në server. Serveri zbulon automatikisht fillimin e të folurit të përdoruesit, duke përdorur mbushjen e prefiksit për të shmangur prerjen e fillimit të shprehjeve.
  2. Klienti përdor një VAD në anën e klientit për të zbuluar kur përdoruesi ndalon së foluri.
  3. Kur VAD në anën e klientit zbulon fundin e të folurit, ai dërgon një sinjal audio_stream_end në server.
  4. Serveri e trajton sinjalin audio_stream_end si një njoftim të menjëhershëm finalizimi, duke anashkaluar vonesën e parazgjedhur të zbulimit të heshtjes në anën e serverit dhe duke kthyer transkriptin dhe përgjigjen e modelit me vonesë minimale.
  5. Nëse VAD-i në anën e klientit dështon të aktivizohet, VAD-i në anën e serverit vepron si një rezervë për të zbuluar fundin e të folurit.

Vini re se nëse pragu i VAD-it në anën e klientit është vendosur shumë agresivisht, kjo mund të shkaktojë ndërprerje të të folurit. Megjithatë, kjo qasje parandalon problemet e shkurtimit të përparmë që mund të ndodhin me VAD-in manual.

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

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

Mund të konfiguroni mediaResolution për seanca multimodale që përfshijnë hyrje audio, video ose imazhi. Ndërsa mediaResolution rregullon shpërndarjen e tokenëve për kornizë për hyrjet vizuale, transmetimet audio tokenizohen me një shpejtësi fikse për sekondë në të gjitha cilësimet e rezolucionit. Për më shumë informacion, shihni udhëzuesin e rezolucionit të medias .

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 99 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 , nb
boshnjak bs Odia or
bullgar bg Oromo om
birmanisht my Pashto ps
Katalanisht ca persisht fa
Cebuanisht ceb polak pl
Kinezisht (e thjeshtuar) zh-Hans Portugalisht (Brazil) pt-BR
Kinezisht (Tradicionale) zh-Hant Portugalisht (Portugali) pt-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 he 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