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 thinkingBudget0 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 behaviorNON_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_audiotrue në konfigurimin proactivity (kërkon v1beta ).
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_dialogtrue në konfigurimin e sesionit (kërkon v1beta ).

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