Questa pagina è stata tradotta dall'API Cloud Translation.

Live API

L'API Live consente interazioni vocali e video bidirezionali a bassa latenza con Gemini, consentendoti di parlare con Gemini in tempo reale e di trasmettere in streaming l'input video o condividere lo schermo. Con l'API Live, puoi offrire agli utenti finali l'esperienza di conversazioni vocali naturali e simili a quelle umane.

Puoi provare l'API Live in Google AI Studio. Per utilizzare l'API Live in Google AI Studio, seleziona Stream.

Come funziona l'API Live

Streaming

L'API Live utilizza un modello di streaming tramite una connessione WebSocket. Quando interagisci con l'API, viene creata una connessione permanente. L'input (audio, video o testo) viene trasmesso in streaming continuo al modello e la risposta del modello (testo o audio) viene trasmessa in streaming in tempo reale sulla stessa connessione.

Questo streaming bidirezionale garantisce una bassa latenza e supporta funzionalità come il rilevamento dell'attività vocale, l'utilizzo dello strumento e la generazione di voce.

Panoramica dell'API Live

Per saperne di più sull'API WebSockets sottostante, consulta il riferimento all'API WebSockets.

Generazione di output

L'API Live elabora input multimodali (testo, audio, video) per generare testo o audio in tempo reale. È dotato di un meccanismo integrato per generare audio e, a seconda della versione del modello in uso, utilizza uno dei due metodi di generazione audio:

Metà cascata: il modello riceve input audio nativo e utilizza una cascata di modelli specializzati di modelli distinti per elaborare l'input e generare l'output audio.
Nativo: Gemini 2.5 introduce la generazione di audio nativo, che genera direttamente l'output audio, offrendo un audio più naturale, voci più espressive, una maggiore consapevolezza del contesto aggiuntivo, ad esempio il tono, e risposte più proattive.

Creazione con l'API Live

Prima di iniziare a creare contenuti con l'API Live, scegli l'approccio di generazione dell'audio più adatto alle tue esigenze.

Creazione di una connessione

L'esempio seguente mostra come creare una connessione con una chiave API:

PythonJavaScript

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

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

Invio e ricezione di messaggi

Ecco come inviare e ricevere messaggi:

PythonJavaScript

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

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

Invio e ricezione di audio

Puoi inviare l'audio convertendolo in formato mono PCM a 16 bit e 16 kHz. Questo esempio legge un file WAV e lo invia nel formato corretto:

PythonJavaScript

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

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

Puoi ricevere l'audio impostando AUDIO come modalità di risposta. Questo esempio salva i dati ricevuti come file WAV:

PythonJavaScript

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 response in session.receive():
            if response.data is not None:
                wf.writeframes(response.data)

            # Un-comment this code to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

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

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

Formati audio

I dati audio nell'API Live sono sempre non elaborati, little-endian e PCM a 16 bit. L'uscita audio utilizza sempre una frequenza di campionamento di 24 kHz. L'audio di input è in modo nativo a 16 kHz, ma l'API Live eseguirà il ricampionamento se necessario in modo da poter inviare qualsiasi frequenza di campionamento. Per trasmettere la frequenza di campionamento dell'audio di input, imposta il tipo MIME di ogni blob contenente audio su un valore come audio/pcm;rate=16000.

Ricevere trascrizioni audio

Puoi attivare la trascrizione dell'output audio del modello inviando output_audio_transcription nella configurazione di configurazione. La lingua della trascrizione viene ricavata dalla risposta del modello.

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

Puoi attivare la trascrizione dell'input audio inviando input_audio_transcription nella configurazione di setup.

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

Riproduzione in streaming di audio e video

Istruzioni di sistema

Le istruzioni di sistema ti consentono di indirizzare il comportamento di un modello in base alle tue esigenze e ai tuoi casi d'uso specifici. Le istruzioni di sistema possono essere impostate nella configurazione di setup e rimarranno in vigore per l'intera sessione.

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

Aggiornamenti incrementali dei contenuti

Utilizza gli aggiornamenti incrementali per inviare input di testo, stabilire il contesto della sessione o ripristinare il contesto della sessione. Per contesti brevi, puoi inviare interazioni passo passo per rappresentare la sequenza esatta di eventi:

PythonJSON

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)

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

Per contesti più lunghi, ti consigliamo di fornire un riepilogo di un singolo messaggio per liberare la finestra di contesto per le interazioni successive.

Cambiare voce e lingua

L'API Live supporta le seguenti voci: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus e Zephyr.

Per specificare una voce, imposta il nome della voce all'interno dell'oggetto speechConfig come parte della configurazione della sessione:

PythonJSON

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

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

L'API Live supporta più lingue.

Per cambiare la lingua, imposta il codice lingua all'interno dell'oggetto speechConfig come parte della configurazione della sessione:

from google.genai import types

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

Uscita audio nativa

Tramite l'API Live, puoi anche accedere a modelli che consentono l'output audio nativo oltre all'input audio nativo. Ciò consente di ottenere output audio di qualità superiore con un ritmo, una naturalezza della voce, una verbosità e uno stato d'animo migliori.

L'output audio nativo è supportato dai seguenti modelli audio nativi:

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

Come utilizzare l'uscita audio nativa

Per utilizzare l'output audio nativo, configura uno dei modelli audio nativi e imposta response_modalities su AUDIO.

Per un esempio completo, vedi Invio e ricezione di audio.

PythonJavaScript

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

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

async function main() {

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

    // Send audio input and receive audio

    session.close();
}

main();

Dialogo emotivo

Questa funzionalità consente a Gemini di adattare il proprio stile di risposta all'espressione e al tono di input.

Per utilizzare la conversazione emotiva, imposta la versione dell'API su v1alpha e imposta enable_affective_dialog su true nel messaggio di configurazione:

PythonJavaScript

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

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

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

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

Tieni presente che al momento il dialogo emotivo è supportato solo dai modelli di output audio nativi.

Audio proattivo

Quando questa funzionalità è attivata, Gemini può decidere in modo proattivo di non rispondere se i contenuti non sono pertinenti.

Per utilizzarlo, imposta la versione dell'API su v1alpha e configura il campo proactivity nel messaggio di configurazione e imposta proactive_audio su true:

PythonJavaScript

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

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

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

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

Tieni presente che l'audio proattivo è attualmente supportato solo dai modelli di output audio nativo.

Uscita audio nativa con pensiero

L'output audio nativo supporta le funzionalità di pensiero, disponibili tramite un modello separato gemini-2.5-flash-exp-native-audio-thinking-dialog.

Per un esempio completo, vedi Invio e ricezione di audio.

Python JavaScript

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

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

async function main() {

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

    // Send audio input and receive audio

    session.close();
}

main();

Utilizzo dello strumento con l'API Live

Con l'API Live puoi definire strumenti come chiamate di funzioni, esecuzione di codice e Ricerca Google.

Panoramica degli strumenti supportati

Ecco una breve panoramica degli strumenti disponibili per ogni modello:

Strumento	Modelli a cascata `gemini-2.0-flash-live-001`	`gemini-2.5-flash-preview-native-audio-dialog`	`gemini-2.5-flash-exp-native-audio-thinking-dialog`
Ricerca	Sì	Sì	Sì
Chiamata di funzione	Sì	Sì	No
Esecuzione del codice	Sì	No	No
Contesto URL	Sì	No	No

Chiamata di funzione

Puoi definire le dichiarazioni di funzione come parte della configurazione della sessione. Per saperne di più, consulta il tutorial sulle chiamate di funzione.

Dopo aver ricevuto le chiamate allo strumento, il client deve rispondere con un elenco di oggetti FunctionResponse utilizzando il metodo 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())

Da un singolo prompt, il modello può generare più chiamate di funzione e il codice necessario per collegarne gli output. Questo codice viene eseguito in un ambiente sandbox, generando messaggi BidiGenerateContentToolCall successivi.

Chiamate di funzioni asincrone

Per impostazione predefinita, l'esecuzione viene messa in pausa fino a quando non sono disponibili i risultati di ogni chiamata di funzione, il che garantisce l'elaborazione sequenziale. Ciò significa che non potrai continuare a interagire con il modello durante l'esecuzione delle funzioni.

Se non vuoi bloccare la conversazione, puoi chiedere al modello di eseguire le funzioni in modo asincrono.

Per farlo, devi prima aggiungere un behavior alle definizioni di funzione:

  # 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 garantisce che la funzione venga eseguita in modo asincrono, mentre puoi continuare a interagire con il modello.

Poi devi dire al modello come comportarsi quando riceve il valore FunctionResponse utilizzando il parametro scheduling. Può:

Interrompere ciò che sta facendo e comunicarti immediatamente la risposta che ha ricevuto (scheduling="INTERRUPT"),
Attendi il termine dell'operazione in corso (scheduling="WHEN_IDLE"),
In alternativa, non fare nulla e utilizza queste informazioni in un secondo momento durante la discussione (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
      }
  )

Esecuzione del codice

Puoi definire l'esecuzione del codice nell'ambito della configurazione della sessione. Per scoprire di più, consulta il tutorial sull'esecuzione del codice.

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

Grounding con la Ricerca Google

Puoi attivare il grounding con la Ricerca Google nell'ambito della configurazione della sessione. Per saperne di più, consulta il tutorial sull'isolamento.

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

Combinare più strumenti

Puoi combinare più strumenti all'interno dell'API 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}

Gestione delle interruzioni

Gli utenti possono interrompere l'output del modello in qualsiasi momento. Quando il rilevamento dell'attività vocale (VAD) rileva un'interruzione, la generazione in corso viene annullata e ignorata. Nella cronologia della sessione vengono conservate solo le informazioni già inviate al client. Il server invia quindi un messaggio BidiGenerateContentServerContent per segnalare l'interruzione.

Inoltre, il server Gemini ignora le chiamate di funzione in attesa e invia un messaggio BidiGenerateContentServerContent con gli ID delle chiamate annullate.

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

Rilevamento attività vocale (VAD)

Puoi configurare o disattivare il rilevamento dell'attività vocale (VAD).

Utilizzo del rilevamento automatico della voce

Per impostazione predefinita, il modello esegue automaticamente la VAD su un flusso di input audio continuo. La VAD può essere configurata con il campo realtimeInputConfig.automaticActivityDetection della configurazione di configurazione.

Quando lo stream audio viene messo in pausa per più di un secondo (ad esempio perché l'utente ha disattivato il microfono), deve essere inviato un evento audioStreamEnd per svuotare la cache dell'audio. Il client può riprendere l'invio di dati audio in qualsiasi momento.

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

Con send_realtime_input, l'API risponderà automaticamente all'audio in base al VAD. Sebbene send_client_content aggiunga i messaggi al contesto del modello in ordine, send_realtime_input è ottimizzato per la reattività a scapito dell'ordinamento deterministico.

Configurazione della VAD automatica

Per un maggiore controllo sull'attività VAD, puoi configurare i seguenti parametri. Per ulteriori informazioni, consulta il riferimento API.

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

Disattivare la VAD automatica

In alternativa, la VAD automatica può essere disattivata impostando realtimeInputConfig.automaticActivityDetection.disabled su true nel messaggio di configurazione. In questa configurazione, il client è responsabile del rilevamento della voce dell'utente e dell'invio di messaggi activityStart e activityEnd al momento opportuno. In questa configurazione non viene inviato un audioStreamEnd. Invece, qualsiasi interruzione dello stream viene contrassegnata da un messaggio 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())
    # ...

Conteggio token

Puoi trovare il numero totale di token consumati nel campo usageMetadata del messaggio del server restituito.

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

Estensione della durata della sessione

La durata massima della sessione può essere estesa a illimitata con due meccanismi:

Compressione della finestra di contesto
Ripresa della sessione

Inoltre, prima della fine della sessione riceverai un messaggio GoAway che ti consentirà di intraprendere ulteriori azioni.

Compressione della finestra di contesto

Per consentire sessioni più lunghe ed evitare interruzioni improvvise della connessione, puoi attivare la compressione della finestra di contesto impostando il campo contextWindowCompression nella configurazione della sessione.

In ContextWindowCompressionConfig, puoi configurare un meccanismo a finestra scorrevole e il numero di token che attivano la compressione.

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

Ripresa della sessione

Per impedire la terminazione della sessione quando il server reimposta periodicamente la connessione WebSocket, configura il campo sessionResumption all'interno della configurazione di configurazione.

Se passi questa configurazione, il server invia messaggi SessionResumptionUpdate, che possono essere utilizzati per riprendere la sessione passando l'ultimo token di ripresa come SessionResumptionConfig.handle della connessione successiva.

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

Ricevere un messaggio prima della disconnessione della sessione

Il server invia un messaggio GoAway che indica che la connessione corrente verrà terminata a breve. Questo messaggio include timeLeft, che indica il tempo rimanente e ti consente di intraprendere ulteriori azioni prima che la connessione venga interrotta come ABORTED.

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)

Ricevere un messaggio al termine della generazione

Il server invia un messaggio generationComplete che indica che il modello ha completato la generazione della risposta.

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

Risoluzione dei contenuti multimediali

Puoi specificare la risoluzione dei contenuti multimediali di input impostando il campo mediaResolution nell'ambito della configurazione della sessione:

from google.genai import types

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

Limitazioni

Tieni presenti le seguenti limitazioni dell'API Live quando pianifichi il tuo progetto.

Modalità di risposta

Nella configurazione della sessione puoi impostare una sola modalità di risposta (TEXT o AUDIO) per sessione. L'impostazione di entrambi i valori genera un messaggio di errore di configurazione. Ciò significa che puoi configurare il modello in modo che risponda con testo o audio, ma non con entrambi nella stessa sessione.

Autenticazione client

L'API Live fornisce solo l'autenticazione da server a server e non è consigliata per l'utilizzo diretto del client. L'input del client deve essere instradato tramite un server di applicazioni intermedio per l'autenticazione sicura con l'API Live.

Durata della sessione

La durata della sessione può essere estesa a illimitata attivando la compressione della sessione. Senza compressione, le sessioni solo audio sono limitate a 15 minuti, mentre quelle con audio e video sono limitate a 2 minuti. Il superamento di questi limiti senza compressione interromperà la connessione.

Inoltre, puoi configurare la ripresa della sessione per consentire al client di riprendere una sessione interrotta.

Finestra contestuale

Una sessione ha un limite di finestra di contesto di:

128.000 token per i modelli con uscita audio nativa
32.000 token per altri modelli dell'API Live

Lingue supportate

L'API Live supporta le seguenti lingue.

Lingua	Codice BCP-47
Tedesco (Germania)	de-DE
Inglese (Australia)	en-AU
Inglese (Regno Unito)	en-GB
Inglese (India)	en-IN
Inglese (USA)	en-US
Spagnolo (Stati Uniti)	es-US
Francese (Francia)	fr-FR
Hindi (India)	hi-IN
Portoghese (Brasile)	pt-BR
Arabo (generico)	ar-XA
Spagnolo (Spagna)	es-ES
Francese (Canada)	fr-CA
Indonesiano (Indonesia)	id-ID
Italiano (Italia)	it-IT
Giapponese (Giappone)	ja-JP
Turco (Turchia)	tr-TR
Vietnamita (Vietnam)	vi-VN
Bengalese (India)	bn-IN
Gujarati (India)	gu-IN
Kannada (India)	kn-IN
Malayalam (India)	ml-IN
Marathi (India)	mr-IN
Tamil (India)	ta-IN
Telugu (India)	te-IN
Olandese (Paesi Bassi)	nl-NL
Coreano (Corea del Sud)	ko-KR
Cinese mandarino (Cina)	cmn-CN
Polacco (Polonia)	pl-PL
Russo (Russia)	ru-RU
Thailandese (Thailandia)	th-TH

Integrazioni di terze parti

Per i deployment di app web e mobile, puoi esplorare le opzioni disponibili in:

Passaggi successivi

Prova l'API Live in Google AI Studio.
Per ulteriori informazioni su Gemini 2.0 Flash Live, consulta la pagina del modello.
Prova altri esempi nel cookbook dell'API Live, nel cookbook degli strumenti dell'API Live e nello script Inizia a utilizzare l'API Live.