Live API capabilities guide

Si tratta di una guida completa che illustra le funzionalità e le configurazioni disponibili con l'API Live. Consulta la pagina Inizia a utilizzare l'API Live per una panoramica e un codice campione per i casi d'uso comuni.

Prima di iniziare

  • Acquisisci familiarità con i concetti di base:se non l'hai ancora fatto, leggi prima la pagina Inizia a utilizzare l'API Live . Verranno illustrati i principi fondamentali dell'API Live, il suo funzionamento e i diversi approcci di implementazione.
  • Prova l'API Live in AI Studio:potrebbe esserti utile provare l'API Live in Google AI Studio prima di iniziare a creare. Per utilizzare l'API Live in Google AI Studio, seleziona Stream.

Confronto modelli

La seguente tabella riepiloga le principali differenze tra i modelli Gemini 3.1 Flash Live Preview e Gemini 2.5 Flash Live Preview:

Funzionalità Anteprima live di Gemini 3.1 Flash Anteprima live di Gemini 2.5 Flash
Ragionamento Utilizza thinkingLevel per controllare la profondità del pensiero con impostazioni come minimal, low, medium e high. Il valore predefinito è minimal per ottimizzare la latenza più bassa. Consulta la sezione Livelli e budget di pensiero. Utilizza thinkingBudget per impostare il numero di token di pensiero. Il pensiero dinamico è abilitato per impostazione predefinita. Imposta thinkingBudget su 0 per disattivare. Consulta la sezione Livelli e budget di pensiero.
Ricezione della risposta Un singolo evento server può contenere più parti di contenuti contemporaneamente (ad esempio, inlineData e trascrizione). Assicurati che il codice elabori tutte le parti di ogni evento per evitare di perdere contenuti. Ogni evento server contiene una sola parte di contenuti. Le parti vengono pubblicate in eventi separati.
Contenuti del cliente send_client_content è supportato solo per l'inizializzazione della cronologia del contesto iniziale (richiede l'impostazione di initial_history_in_client_content nella configurazione della sessione). Per inviare aggiornamenti di testo durante la conversazione, utilizza send_realtime_input. send_client_content è supportato durante tutta la conversazione per l'invio di aggiornamenti incrementali dei contenuti e per stabilire il contesto.
Copertura svolta Il valore predefinito è TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO. Il turno del modello include l'attività audio rilevata e tutti i fotogrammi video. Il valore predefinito è TURN_INCLUDES_ONLY_ACTIVITY. Il turno del modello include solo l'attività rilevata.
VAD personalizzato (activity_start/activity_end) Supportato. Disattiva il VAD automatico e invia manualmente i messaggi activityStart e activityEnd per controllare i limiti dei turni. Supportato. Disattiva il VAD automatico e invia manualmente i messaggi activityStart e activityEnd per controllare i limiti dei turni.
Configurazione automatica del VAD Supportato. Configura parametri come start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms e silence_duration_ms. Supportato. Configura parametri come start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms e silence_duration_ms.
Chiamata di funzione asincrona (behavior: NON_BLOCKING) Non supportato. La chiamata di funzioni è solo sequenziale. Il modello non inizierà a rispondere finché non avrai inviato la risposta dello strumento. Supportato. Imposta behavior su NON_BLOCKING in una dichiarazione di funzione per consentire al modello di continuare a interagire durante l'esecuzione della funzione. Controlla il modo in cui il modello gestisce le risposte con il parametro scheduling (INTERRUPT, WHEN_IDLE o SILENT).
Audio proattivo Non supportato Supportato. Se questa opzione è attivata, il modello può decidere in modo proattivo di non rispondere se i contenuti dell'input non sono pertinenti. Imposta proactive_audio su true nella configurazione proactivity (richiede v1alpha).
Dialogo empatico Non supportato Supportato. Il modello adatta il suo stile di risposta in modo che corrisponda all'espressione e al tono dell'input. Imposta enable_affective_dialog su true nella configurazione della sessione (richiede v1alpha).

Per eseguire la migrazione da Gemini 2.5 Flash Live a Gemini 3.1 Flash Live, consulta la guida alla migrazione.

Creazione di una connessione

Il seguente esempio mostra come creare una connessione con una chiave 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();

Modalità di interazione

Le sezioni seguenti forniscono esempi e contesto di supporto per le diverse modalità di input e output disponibili nell'API Live.

Invio dell'audio

L'audio deve essere inviato come dati PCM non elaborati (audio PCM non elaborato a 16 bit, 16 kHz, 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'
  }
});

Formati audio

I dati audio nell'API Live sono sempre grezzi, little-endian, PCM a 16 bit. L'uscita audio utilizza sempre una frequenza di campionamento di 24 kHz. L'audio di input è nativamente a 16 kHz, ma l'API Live esegue il ricampionamento se necessario in modo che sia possibile inviare qualsiasi frequenza di campionamento. Per indicare 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.

Ricezione dell'audio

Le risposte audio del modello vengono ricevute come blocchi di dati.

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

Invio dell'SMS in corso…

Il testo può essere inviato utilizzando send_realtime_input (Python) o sendRealtimeInput (JavaScript).

Python

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

JavaScript

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

Invio del video

I fotogrammi video vengono inviati come singole immagini (ad es.JPEG o PNG) a una frequenza fotogrammi specifica (max. 1 fotogramma al secondo).

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

Aggiornamenti incrementali dei contenuti

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

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

Per contesti più lunghi, è consigliabile fornire un riepilogo di un singolo messaggio per liberare la finestra contestuale per le interazioni successive. Consulta la sezione Ripresa delle sessioni per un altro metodo di caricamento del contesto della sessione.

Trascrizioni audio

Oltre alla risposta del modello, puoi anche ricevere le trascrizioni dell'uscita audio e dell'input audio.

Per attivare la trascrizione dell'uscita audio del modello, invia output_audio_transcription nella configurazione di configurazione. La lingua della trascrizione viene dedotta dalla risposta del modello.

Python

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

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

config = {
    "response_modalities": ["AUDIO"],
    "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';

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

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'Hello how are you?';
  session.sendClientContent({ turns: inputTurns });

  const turns = await handleTurn();

  for (const turn of turns) {
    if (turn.serverContent && turn.serverContent.outputTranscription) {
      console.debug('Received output transcription: %s\n', turn.serverContent.outputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

Per attivare la trascrizione dell'input audio del modello, invia input_audio_transcription nella configurazione di configurazione.

Python

import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},
}

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

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

        async for msg in session.receive():
            if msg.server_content.input_transcription:
                print('Transcript:', msg.server_content.input_transcription.text)

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

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile';
const { WaveFile } = pkg;

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';

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

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  // Send Audio Chunk
  const fileBuffer = fs.readFileSync("16000.wav");

  // Ensure audio conforms to API requirements (16-bit PCM, 16kHz, mono)
  const wav = new WaveFile();
  wav.fromBuffer(fileBuffer);
  wav.toSampleRate(16000);
  wav.toBitDepth("16");
  const base64Audio = wav.toBase64();

  // If already in correct format, you can use this:
  // const fileBuffer = fs.readFileSync("sample.pcm");
  // const base64Audio = Buffer.from(fileBuffer).toString('base64');

  session.sendRealtimeInput(
    {
      audio: {
        data: base64Audio,
        mimeType: "audio/pcm;rate=16000"
      }
    }
  );

  const turns = await handleTurn();
  for (const turn of turns) {
    if (turn.text) {
      console.debug('Received text: %s\n', turn.text);
    }
    else if (turn.data) {
      console.debug('Received inline data: %s\n', turn.data);
    }
    else if (turn.serverContent && turn.serverContent.inputTranscription) {
      console.debug('Received input transcription: %s\n', turn.serverContent.inputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

Cambiare voce e lingua

I modelli di uscita audio nativa supportano una qualsiasi delle voci disponibili per i nostri modelli di Text-to-Speech (TTS). Puoi ascoltare tutte le voci in AI Studio.

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

Python

config = {
    "response_modalities": ["AUDIO"],
    "speech_config": {
        "voice_config": {"prebuilt_voice_config": {"voice_name": "Kore"}}
    },
}

JavaScript

const config = {
  responseModalities: [Modality.AUDIO],
  speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } }
};

L'API Live supporta più lingue. I modelli di uscita audio nativa scelgono automaticamente la lingua appropriata e non supportano l'impostazione esplicita del codice della lingua.

Funzionalità audio native

I nostri modelli più recenti sono dotati di uscita audio nativa, che offre una voce naturale e realistica e prestazioni multilingue migliorate.

Ragionamento

I modelli Gemini 3.1 utilizzano thinkingLevel per controllare la profondità del pensiero, con impostazioni come minimal, low, medium e high. Il valore predefinito è minimal per ottimizzare la latenza più bassa. I modelli Gemini 2.5 utilizzano thinkingBudget per impostare il numero di token di pensiero. Per ulteriori dettagli sui livelli e sui budget, consulta Livelli e budget.

Python 

model = "gemini-3.1-flash-live-preview"

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

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio input and receive audio

JavaScript

const model = 'gemini-3.1-flash-live-preview';
const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingLevel: 'low',
  },
};

async function main() {

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

  // Send audio input and receive audio

  session.close();
}

main();

Inoltre, puoi attivare i riepiloghi dei pensieri impostando includeThoughts su true nella configurazione. Per maggiori informazioni, consulta la sezione Riepiloghi dei pensieri:

Python 

model = "gemini-3.1-flash-live-preview"

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

JavaScript

const model = 'gemini-3.1-flash-live-preview';
const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingLevel: 'low',
    includeThoughts: true,
  },
};

Dialogo empatico

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

Per utilizzare il dialogo empatico, imposta la versione dell'API su v1alpha e imposta enable_affective_dialog su true nel messaggio di configurazione:

Python

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

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

JavaScript

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

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

Audio proattivo

Quando questa funzionalità è attiva, 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:

Python

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

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

JavaScript

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

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

Rilevamento dell'attività vocale (VAD)

Il rilevamento dell'attività vocale (VAD) consente al modello di riconoscere quando una persona sta parlando. Ciò è essenziale per creare conversazioni naturali, in quanto consente a un utente di interrompere il modello in qualsiasi momento.

Quando VAD rileva un'interruzione, la generazione in corso viene annullata e ignorata. Nella cronologia della sessione vengono conservate solo le informazioni già inviate al cliente. Il server invia quindi un messaggio BidiGenerateContentServerContent per segnalare l'interruzione.

Il server Gemini scarta quindi tutte le chiamate di funzione in attesa e invia un messaggio BidiGenerateContentServerContent con gli ID delle chiamate annullate.

Python

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

        # If realtime playback is implemented in your application,
        # you should stop playing audio and clear queued playback here.

JavaScript

const turns = await handleTurn();

for (const turn of turns) {
  if (turn.serverContent && turn.serverContent.interrupted) {
    // The generation was interrupted

    // If realtime playback is implemented in your application,
    // you should stop playing audio and clear queued playback here.
  }
}

VAD automatico

Per impostazione predefinita, il modello esegue automaticamente il rilevamento dell'attività vocale su un flusso di input audio continuo. VAD può essere configurato con il campo realtimeInputConfig.automaticActivityDetection della configurazione di configurazione.

Quando il flusso 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 l'audio memorizzato nella cache. Il client può riprendere l'invio dei dati audio in qualsiasi momento.

Python

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-3.1-flash-live-preview"

config = {"response_modalities": ["AUDIO"]}

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

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

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

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

JavaScript

// example audio file to try:
// URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
// !wget -q $URL -O sample.pcm
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  // Send Audio Chunk
  const fileBuffer = fs.readFileSync("sample.pcm");
  const base64Audio = Buffer.from(fileBuffer).toString('base64');

  session.sendRealtimeInput(
    {
      audio: {
        data: base64Audio,
        mimeType: "audio/pcm;rate=16000"
      }
    }

  );

  // if stream gets paused, send:
  // session.sendRealtimeInput({ audioStreamEnd: true })

  const turns = await handleTurn();
  for (const turn of turns) {
    if (turn.text) {
      console.debug('Received text: %s\n', turn.text);
    }
    else if (turn.data) {
      console.debug('Received inline data: %s\n', turn.data);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

Con send_realtime_input, l'API risponderà automaticamente all'audio in base al rilevamento dell'attività vocale. Mentre send_client_content aggiunge i messaggi al contesto del modello in ordine, send_realtime_input è ottimizzato per la reattività a scapito dell'ordine deterministico.

Configurazione automatica del VAD

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

Python

from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

JavaScript

import { GoogleGenAI, Modality, StartSensitivity, EndSensitivity } from '@google/genai';

const config = {
  responseModalities: [Modality.AUDIO],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: false, // default
      startOfSpeechSensitivity: StartSensitivity.START_SENSITIVITY_LOW,
      endOfSpeechSensitivity: EndSensitivity.END_SENSITIVITY_LOW,
      prefixPaddingMs: 20,
      silenceDurationMs: 100,
    }
  }
};

Disattivare il rilevamento automatico dell'attività vocale

In alternativa, il VAD automatico può essere disattivato 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 dei messaggi activityStart e activityEnd al momento opportuno. Un audioStreamEnd non viene inviato in questa configurazione. Qualsiasi interruzione dello stream viene invece contrassegnata da un messaggio activityEnd.

Python

config = {
    "response_modalities": ["AUDIO"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

JavaScript

const config = {
  responseModalities: [Modality.AUDIO],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: true,
    }
  }
};

session.sendRealtimeInput({ activityStart: {} })

session.sendRealtimeInput(
  {
    audio: {
      data: base64Audio,
      mimeType: "audio/pcm;rate=16000"
    }
  }

);

session.sendRealtimeInput({ activityEnd: {} })

Conteggio dei token

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

Python

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

JavaScript

const turns = await handleTurn();

for (const turn of turns) {
  if (turn.usageMetadata) {
    console.debug('Used %s tokens in total. Response token breakdown:\n', turn.usageMetadata.totalTokenCount);

    for (const detail of turn.usageMetadata.responseTokensDetails) {
      console.debug('%s\n', detail);
    }
  }
}

Risoluzione dei contenuti multimediali

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

Python

from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "media_resolution": types.MediaResolution.MEDIA_RESOLUTION_LOW,
}

JavaScript

import { GoogleGenAI, Modality, MediaResolution } from '@google/genai';

const config = {
    responseModalities: [Modality.AUDIO],
    mediaResolution: MediaResolution.MEDIA_RESOLUTION_LOW,
};

Limitazioni

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

Modalità di risposta

I modelli audio nativi supportano solo la modalità di risposta `AUDIO`. Se hai bisogno della risposta del modello come testo, utilizza la funzionalità di trascrizione dell'audio di output.

Autenticazione client

L'API Live fornisce solo l'autenticazione server-server per impostazione predefinita. Se implementi l'applicazione Live API utilizzando un approccio client-server, devi utilizzare token effimeri per ridurre i rischi per la sicurezza.

Durata della sessione

Le sessioni solo audio sono limitate a 15 minuti, mentre le sessioni audio più video sono limitate a 2 minuti. Tuttavia, puoi configurare diverse tecniche di gestione delle sessioni per estensioni illimitate della durata della sessione.

Finestra contestuale

Una sessione ha un limite della finestra contestuale 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 97 lingue.

Lingua Codice BCP-47 Lingua Codice BCP-47
Afrikaans af Lettone lv
Akan ak Lituano lt
Albanese sq Macedone mk
Amarico am Malese ms
Arabo ar Malayalam ml
Armeno hy Maltese mt
Assamese as Maori mi
Azero az Marathi mr
Basco eu Mongolo mn
Bielorusso be Nepalese ne
Bengalese bn Norvegese no
Bosniaco bs Odia or
Bulgaro bg Oromo om
Birmano my Pashto ps
Catalano ca Persiano fa
Cebuano ceb Polacco pl
Cinese zh Portoghese pt
Croato hr Punjabi pa
Ceco cs Quechua qu
Danese da Rumeno ro
Olandese nl Romancio rm
Inglese en Russo ru
Estone et Serbo sr
Faroese fo Sindhi sd
Filippino fil Singalese si
Finlandese fi Slovacco sk
Francese fr Sloveno sl
Galiziano gl Somalo so
Georgiano ka Sotho del sud st
Tedesco de Spagnolo es
Greco el Swahili sw
Gujarati gu Svedese sv
Hausa ha Tagico tg
Ebraico iw Tamil ta
Hindi hi Telugu te
Ungherese hu Thailandese th
Islandese is Tswana tn
Indonesiano id Turco tr
Irlandese ga Turkmeno tk
Italiano it Ucraino uk
Giapponese ja Urdu ur
Kannada kn Uzbeco uz
Kazako kk Vietnamita vi
Khmer km Gallese cy
Kinyarwanda rw Frisone occidentale fy
Coreano ko Wolof wo
Curdo ku Yoruba yo
Kirgizo ky Zulu zu
Lao lo

Passaggi successivi