Live API

Live API mundëson ndërveprime zanore dhe video me vonesë të ulët me Gemini, duke ju lejuar të flisni me Gemini drejtpërdrejt ndërsa transmetoni hyrjen e videos ose ndani ekranin tuaj. Duke përdorur Live API, ju mund t'u ofroni përdoruesve fundorë përvojën e bisedave zanore natyrale, të ngjashme me njerëzit.

Mund të provoni Live API në Google AI Studio . Për të përdorur API-në e drejtpërdrejtë në Google AI Studio, zgjidhni Transmeto .

Si funksionon Live API

Transmetim

Live API përdor një model transmetimi mbi një lidhje WebSocket . Kur ndërveproni me API-në, krijohet një lidhje e vazhdueshme. Hyrja juaj (audio, video ose tekst) transmetohet vazhdimisht në model dhe përgjigja e modelit (tekst ose audio) transmetohet në kohë reale në të njëjtën lidhje.

Ky transmetim me dy drejtime siguron vonesë të ulët dhe mbështet veçori të tilla si zbulimi i aktivitetit të zërit, përdorimi i mjeteve dhe gjenerimi i të folurit.

Përmbledhje e drejtpërdrejtë e API-së

Për më shumë informacion në lidhje me API-në themelore të WebSockets, shihni referencën e WebSockets API .

Prodhimi i prodhimit

Live API përpunon hyrjen multimodale (tekst, audio, video) për të gjeneruar tekst ose audio në kohë reale. Ajo vjen me një mekanizëm të integruar për të gjeneruar audio dhe në varësi të versionit të modelit që përdorni, ai përdor një nga dy metodat e gjenerimit të audios:

  • Gjysma e kaskadës : Modeli merr hyrjen origjinale të audios dhe përdor një kaskadë modeli të specializuar të modeleve të ndryshme për të përpunuar hyrjen dhe për të gjeneruar dalje audio.
  • Native : Gemini 2.5 prezanton gjenerimin vendas të audios , i cili gjeneron drejtpërdrejt dalje audio, duke ofruar një zë më natyral, zëra më shprehës, më shumë ndërgjegjësim për kontekstin shtesë, p.sh. tonin dhe përgjigjet më proaktive.

Ndërtimi me API të drejtpërdrejtë

Përpara se të filloni ndërtimin me Live API, zgjidhni qasjen e gjenerimit të audios që i përshtatet më mirë nevojave tuaja.

Krijimi i 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(api_key="GEMINI_API_KEY")

model = "gemini-2.0-flash-live-001"
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 } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const model = 'gemini-2.0-flash-live-001';
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();

Dërgimi dhe marrja e tekstit

Ja se si mund të dërgoni dhe merrni tekst:

Python 

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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({ apiKey: "GOOGLE_API_KEY" });
const model = 'gemini-2.0-flash-live-001';
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 simple = 'Hello how are you?';
    session.sendClientContent({ turns: simple });

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

Dërgimi dhe marrja e audios

Ju mund të dërgoni audio duke e kthyer atë në formatin 16-bit PCM, 16 kHz, mono. Ky shembull lexon një skedar WAV dhe e dërgon atë në formatin e duhur:

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(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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({ apiKey: "GOOGLE_API_KEY" });
const model = 'gemini-2.0-flash-live-001';
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();

Ju mund të merrni audio duke vendosur AUDIO si modalitet përgjigjeje. Ky shembull ruan të dhënat e marra si skedar WAV:

Python 

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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 idx,response in async_enumerate(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';

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const model = 'gemini-2.0-flash-live-001';
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 simple = 'Hello how are you?';
    session.sendClientContent({ turns: simple });

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

Formatet audio

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

Marrja e transkriptimeve audio

Mund të aktivizoni transkriptimin e daljes audio të modelit duke dërguar output_audio_transcription në konfigurimin e konfigurimit. Gjuha e transkriptimit nxirret nga përgjigja e modelit.

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

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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

Mund të aktivizoni transkriptimin e hyrjes audio duke dërguar input_audio_transcription në konfigurimin e konfigurimit. 

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

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

config = {"response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {"disabled": True},
        "activity_handling": "NO_INTERRUPTION",
    },
    "input_audio_transcription": {},
}

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

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

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

Transmetimi i audios dhe videos

Udhëzimet e sistemit

Udhëzimet e sistemit ju lejojnë të drejtoni sjelljen e një modeli bazuar në nevojat tuaja specifike dhe rastet e përdorimit. Udhëzimet e sistemit mund të vendosen në konfigurimin e konfigurimit dhe do të mbeten në fuqi për të gjithë seancën. 

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

Përditësimet në rritje të përmbajtjes

Përdorni përditësime shtesë për të dërguar të dhëna teksti, 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 kthesë pas kthese 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)

JSON 

{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

Për kontekste më të gjata, rekomandohet të sigurohet një përmbledhje e vetme e mesazhit për të liruar dritaren e kontekstit për ndërveprimet e mëvonshme.

Ndryshimi i zërit dhe gjuhës

API Live mbështet zërat e mëposhtëm: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus dhe Zephyr.

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

Python 

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)

JSON 

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

API Live mbështet shumë gjuhë .

Për të ndryshuar gjuhën, vendosni kodin e gjuhës brenda objektit speechConfig si pjesë e konfigurimit të sesionit: 

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

Dalja origjinale e audios

Nëpërmjet API-së Live, ju gjithashtu mund të përdorni modele që lejojnë daljen e audios vendase përveç hyrjes së audios vendase. Kjo mundëson dalje audio me cilësi më të lartë me ritëm më të mirë, natyralitet të zërit, folje dhe humor.

Dalja origjinale e audios mbështetet nga modelet e mëposhtme të audios vendase :

  • gemini-2.5-flash-preview-native-audio-dialog
  • gemini-2.5-flash-exp-native-audio-thinking-dialog

Si të përdorni daljen e audios amtare

Për të përdorur daljen origjinale të audios, konfiguroni një nga modelet origjinale të audios dhe caktoni response_modalities në AUDIO : 

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

Dialog afektiv

Kjo veçori i lejon Binjakëve të përshtasë stilin e përgjigjes me shprehjen dhe tonin e hyrjes.

Për të përdorur dialogun afektiv, vendosni enable_affective_dialog në true në mesazhin e konfigurimit: 

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

Vini re se dialogu afektiv aktualisht mbështetet vetëm nga modelet e daljes audio vendase.

Audio proaktive

Kur kjo veçori është e aktivizuar, Binjakët mund të vendosin në mënyrë proaktive të mos përgjigjen nëse përmbajtja nuk është e rëndësishme.

Për ta përdorur atë, konfiguroni fushën e proactivity në mesazhin e konfigurimit dhe vendosni proactive_audio në true : 

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

Vini re se audio proaktive aktualisht mbështetet vetëm nga modelet e daljes audio vendase.

Dalje audio vendase me të menduarit

Dalja origjinale e audios mbështet aftësitë e të menduarit , të disponueshme nëpërmjet një modeli të veçantë gemini-2.5-flash-exp-native-audio-thinking-dialog . 

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

Përdorimi i mjetit me Live API

Mund të përcaktoni mjete të tilla si Thirrja e funksionit , ekzekutimi i kodit dhe Kërkimi në Google me API-në e drejtpërdrejtë.

Pasqyrë e mjeteve të mbështetura

Këtu është një përmbledhje e shkurtër e mjeteve të disponueshme për secilin model:

Mjet Modele me kaskadë
gemini-2.0-flash-live-001		 gemini-2.5-flash-preview-native-audio-dialog gemini-2.5-flash-exp-native-audio-thinking-dialog
Kërko po po po
Thirrja e funksionit po po Nr
Ekzekutimi i kodit po Nr Nr
Konteksti i URL-së po Nr Nr

Thirrja e funksionit

Ju mund të përcaktoni deklaratat e funksioneve si pjesë e konfigurimit të sesionit. Shikoni tutorialin e thirrjes së funksionit për të mësuar më shumë.

Pas marrjes së thirrjeve të veglave, klienti duhet të përgjigjet me një listë të objekteve FunctionResponse duke përdorur metodën session.send_tool_response .

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

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


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

Nga një kërkesë e vetme, modeli mund të gjenerojë thirrje të shumëfishta funksionesh dhe kodin e nevojshëm për zinxhirin e daljeve të tyre. Ky kod ekzekutohet në një mjedis sandbox, duke gjeneruar mesazhe të mëvonshme BidiGenerateContentToolCall .

Thirrja e funksionit asinkron

Si parazgjedhje, ekzekutimi ndalon derisa rezultatet e çdo thirrjeje funksioni të jenë të disponueshme, gjë që siguron përpunim vijues. Do të thotë që nuk do të mund të vazhdoni të ndërveproni me modelin gjatë ekzekutimit të funksioneve.

Nëse nuk doni të bllokoni bisedën, mund t'i thoni modelit të ekzekutojë funksionet në mënyrë asinkrone.

Për ta bërë këtë, së pari duhet të shtoni një behavior në përkufizimet e funksionit: 

  # Non-blocking function definitions
  turn_on_the_lights = {"name": "turn_on_the_lights", "behavior": "NON_BLOCKING"} # turn_on_the_lights will run asynchronously
  turn_off_the_lights = {"name": "turn_off_the_lights"} # turn_off_the_lights will still pause all interactions with the model

NON-BLOCKING do të sigurojë që funksioni të funksionojë në mënyrë asinkrone ndërkohë që ju mund të vazhdoni të ndërveproni me modelin.

Pastaj ju duhet t'i tregoni modelit se si të sillet kur merr FunctionResponse duke përdorur parametrin scheduling . Mund ose:

  • Ndërprisni atë që po bën dhe ju tregoni për përgjigjen që mori menjëherë ( scheduling="INTERRUPT" ),
  • Prisni derisa të përfundojë me atë që po bën aktualisht ( scheduling="WHEN_IDLE" ),
  • Ose mos bëni asgjë dhe përdorni atë njohuri më vonë në diskutim ( scheduling="SILENT" ) 
# Non-blocking function definitions
  function_response = types.FunctionResponse(
      id=fc.id,
      name=fc.name,
      response={
          "result": "ok",
          "scheduling": "INTERRUPT" # Can also be WHEN_IDLE or SILENT
      }
  )

Ekzekutimi i kodit

Ju mund të përcaktoni ekzekutimin e kodit si pjesë e konfigurimit të sesionit. Shihni udhëzuesin e ekzekutimit të kodit për të mësuar më shumë. 

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

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

Mund të aktivizoni Grounding me Google Search si pjesë e konfigurimit të sesionit. Shihni tutorialin e tokëzimit për të mësuar më shumë. 

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

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

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

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

Kombinimi i shumë mjeteve

Ju mund të kombinoni shumë mjete brenda API-së Live: 

prompt = """
Hey, I need you to do three things for me.

1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"code_execution": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

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

Trajtimi i ndërprerjeve

Përdoruesit mund të ndërpresin daljen e modelit në çdo kohë. Kur Zbulimi i aktivitetit zanor (VAD) zbulon një ndërprerje, gjenerimi në vazhdim anulohet dhe hidhet poshtë. Vetëm informacioni i dërguar tashmë klientit ruhet në historikun e sesionit. Serveri më pas dërgon një mesazh BidiGenerateContentServerContent për të raportuar ndërprerjen.

Përveç kësaj, serveri Gemini hedh poshtë çdo thirrje funksioni në pritje dhe dërgon një mesazh BidiGenerateContentServerContent me ID-të e thirrjeve të anuluara. 

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

Zbulimi i aktivitetit zanor (VAD)

Mund të konfiguroni ose çaktivizoni zbulimin e aktivitetit zanor (VAD).

Duke përdorur VAD automatike

Si parazgjedhje, modeli kryen automatikisht VAD në një transmetim të vazhdueshëm të hyrjes audio. VAD mund të konfigurohet me fushën realtimeInputConfig.automaticActivityDetection të konfigurimit të konfigurimit .

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

# 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(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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

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 optimizohet për reagim në kurriz të renditjes përcaktuese.

Konfigurimi i VAD-së automatike

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

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

Çaktivizimi i VAD-së automatike

Përndryshe, VAD-i 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 . 

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

Numri i shenjave

Ju mund të gjeni numrin total të argumenteve të konsumuara në fushën usageMetadata të mesazhit të serverit të kthyer. 

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

Zgjatja e kohëzgjatjes së seancës

Kohëzgjatja maksimale e seancës mund të zgjatet në të pakufizuar me dy mekanizma:

Për më tepër, do të merrni një mesazh GoAway përpara përfundimit të seancës, duke ju lejuar të ndërmerrni veprime të mëtejshme.

Kompresimi i dritares së kontekstit

Për të aktivizuar sesione më të gjata dhe për të shmangur ndërprerjen e papritur të lidhjes, mund të aktivizoni ngjeshjen e dritares së kontekstit duke vendosur fushën e kontekstitWindowCompression si pjesë e konfigurimit të sesionit.

Në ContextWindowCompressionConfig , ju mund të konfiguroni një mekanizëm me dritare rrëshqitëse dhe numrin e shenjave që nxisin kompresimin. 

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Rifillimi i seancës

Për të parandaluar përfundimin e sesionit kur serveri rivendos periodikisht lidhjen WebSocket, konfiguroni fushën sessionResumption brenda konfigurimit të konfigurimit .

Kalimi i këtij konfigurimi bën që serveri të dërgojë mesazhe SessionResumptionUpdate , të cilat mund të përdoren për të rifilluar seancën duke kaluar shenjën e fundit të rifillimit si SessionResumptionConfig.handle e lidhjes pasuese. 

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

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        config=types.LiveConnectConfig(
            response_modalities=["AUDIO"],
            session_resumption=types.SessionResumptionConfig(
                # The handle of the session to resume is passed here,
                # or else None to start a new session.
                handle=previous_session_handle
            ),
        ),
    ) as session:
        while True:
            await session.send_client_content(
                turns=types.Content(
                    role="user", parts=[types.Part(text="Hello world!")]
                )
            )
            async for message in session.receive():
                # Periodically, the server will send update messages that may
                # contain a handle for the current state of the session.
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        # The handle should be retained and linked to the session.
                        return update.new_handle

                # For the purposes of this example, placeholder input is continually fed
                # to the model. In non-sample code, the model inputs would come from
                # the user.
                if message.server_content and message.server_content.turn_complete:
                    break

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

Marrja e një mesazhi përpara se seanca të shkëputet

Serveri dërgon një mesazh GoAway që sinjalizon se lidhja aktuale do të ndërpritet së shpejti. Ky mesazh përfshin timeLeft , që tregon kohën e mbetur dhe ju lejon të ndërmerrni veprime të mëtejshme përpara se lidhja të ndërpritet si E ABORTUAR. 

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

Marrja e një mesazhi kur gjenerimi të ketë përfunduar

Serveri dërgon një mesazh gjenerimi i plotë që sinjalizon se modeli ka përfunduar gjenerimin e përgjigjes. 

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

Rezolucioni i medias

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

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Kufizimet

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

Modalitetet e reagimit

Mund të vendosni vetëm një modalitet përgjigjeje ( TEXT ose AUDIO ) për sesion në konfigurimin e sesionit. Vendosja e të dyjave rezulton në një mesazh gabimi të konfigurimit. Kjo do të thotë që ju mund ta konfiguroni modelin që të përgjigjet me tekst ose audio, por jo të dyja në të njëjtin seancë.

Autentifikimi i klientit

Live API ofron vetëm vërtetim nga serveri në server dhe nuk rekomandohet për përdorim të drejtpërdrejtë të klientit. Hyrja e klientit duhet të drejtohet përmes një serveri të ndërmjetëm aplikacioni për vërtetim të sigurt me Live API.

Kohëzgjatja e seancës

Kohëzgjatja e sesionit mund të zgjatet në të pakufizuar duke aktivizuar kompresimin e sesionit. Pa kompresim, seancat vetëm me audio janë të kufizuara në 15 minuta dhe seancat audio plus video janë të kufizuara në 2 minuta. Tejkalimi i këtyre kufijve pa kompresim do të ndërpresë lidhjen.

Për më tepër, mund të konfiguroni rifillimin e sesionit për të lejuar klientin të rifillojë një sesion që është përfunduar.

Dritarja e kontekstit

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

Gjuhët e mbështetura

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

Gjuha Kodi i PKK-47
gjermanisht (Gjermani) de-DE
anglisht (Australi) en-AU
Anglisht (Mbretëria e Bashkuar) en-GB
anglisht (Indi) en-IN
anglisht (SHBA) en-SHBA
Spanjisht (Shtetet e Bashkuara të Amerikës) es-SHBA
Frëngjisht (Francë) fr-FR
Hindi (Indi) hi-IN
Portugeze (Brazil) pt-BR
Arabisht (Gjenerike) ar-XA
spanjisht (Spanjë) es-ES
Frëngjisht (Kanada) fr-CA
Indonezisht (Indonezi) ID-ID
italisht (Itali) it-IT
japoneze (Japoni) ja-JP
turqisht (Turqi) tr-TR
Vietnamisht (Vietnam) vi-VN
Bengalisht (Indi) bn-IN
Guxharatisht (Indi) gu-IN
Kanada (Indi) kn-IN
Malajalame (Indi) ml-IN
Marathi (Indi) mr-IN
Tamile (Indi) ta-IN
telugu (Indi) te-IN
Hollandisht (Holandë) nl-NL
Koreane (Koreja e Jugut) ko-KR
Mandarin kineze (Kinë) cmn-CN
polake (Poloni) pl-PL
Rusisht (Rusi) ru-RU
Thai (Tajlandë) th-TH

Integrimet e palëve të treta

Për vendosjen e aplikacioneve në ueb dhe celular, mund të eksploroni opsionet nga:

Çfarë është më pas