Riferimento API Live

L'API Live consente interazioni vocali e video bidirezionali a bassa latenza con Gemini. Utilizzando l'API Live, puoi offrire agli utenti finali l'esperienza di conversazioni vocali naturali e simili a quelle umane, nonché la possibilità di interrompere le risposte del modello utilizzando i comandi vocali. L'API Live può elaborare input di testo, audio e video e fornire output di testo e audio.

Per saperne di più sull'API Live, consulta la pagina API Live.

Funzionalità

L'API Live include le seguenti funzionalità principali:

• Multimodalità: il modello può vedere, sentire e parlare.
• Interazione in tempo reale a bassa latenza: il modello può fornire risposte rapide.
• Memoria della sessione: il modello conserva la memoria di tutte le interazioni all'interno di una singola sessione, ricordando le informazioni sentite o viste in precedenza.
• Supporto della chiamata di funzioni, dell'esecuzione di codice e della ricerca come strumento: puoi integrare il modello con servizi e origini dati esterni.

L'API Live è progettata per la comunicazione server-server.

Per le app web e mobile, ti consigliamo di utilizzare l'integrazione dei nostri partner su Daily.

Modelli supportati

• Gemini 2.5 Flash con audio nativo dell'API Live
  previewAnteprima
• Gemini 2.0 Flash con API Live
  previewAnteprima
• Gemini 2.5 Flash

Inizia

Per provare l'API live, vai a Vertex AI Studio, quindi fai clic su Avvia sessione.

L'API Live è un'API stateful che utilizza WebSockets.

Questa sezione mostra un esempio di come utilizzare l'API Live per la generazione di testo, utilizzando Python 3.9+.

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    HttpOptions,
    Modality,
    Part,
)

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-live-preview-04-09"

async with client.aio.live.connect(
    model=model_id,
    config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
) as session:
    text_input = "Hello? Gemini, are you there?"
    print("> ", text_input, "\n")
    await session.send_client_content(turns=Content(role="user", parts=[Part(text=text_input)]))

    response = []

    async for message in session.receive():
        if message.text:
            response.append(message.text)

    print("".join(response))
# Example output:
# >  Hello? Gemini, are you there?
# Yes, I'm here. What would you like to talk about?

Guida all'integrazione

Questa sezione descrive il funzionamento dell'integrazione con l'API Live.

Sessioni

Una connessione WebSocket stabilisce una sessione tra il client e il server Gemini.

Dopo che un client avvia una nuova connessione, la sessione può scambiare messaggi con il server per:

• Invia testo, audio o video al server Gemini.
• Ricevere richieste di audio, testo o chiamate di funzioni dal server Gemini.

La configurazione della sessione viene inviata nel primo messaggio dopo la connessione. Una configurazione della sessione include il modello, i parametri di generazione, le istruzioni di sistema e gli strumenti.

Vedi la seguente configurazione di esempio:

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

Per maggiori informazioni, consulta BidiGenerateContentSetup.

Inviare messaggi

I messaggi sono oggetti in formato JSON scambiati tramite la connessione WebSocket.

Per inviare un messaggio, il client deve inviare un oggetto JSON tramite una connessione WebSocket aperta. L'oggetto JSON deve contenere esattamente uno dei campi del seguente insieme di oggetti:

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Messaggi dei clienti supportati

Consulta i messaggi del client supportati nella tabella seguente:

Ricevere messaggi

Per ricevere messaggi da Gemini, ascolta l'evento WebSocket "message", quindi analizza il risultato in base alla definizione dei messaggi del server supportati.

Vedi quanto segue:

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

I messaggi del server avranno esattamente uno dei campi del seguente set di oggetti:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
  "usageMetadata": UsageMetadata
  "goAway": GoAway
  "sessionResumptionUpdate": SessionResumptionUpdate
  "inputTranscription": BidiGenerateContentTranscription
  "outputTranscription": BidiGenerateContentTranscription
}

Messaggi del server supportati

Consulta i messaggi del server supportati nella tabella seguente:

Aggiornamenti incrementali dei contenuti

Utilizza gli aggiornamenti incrementali per inviare l'input di testo, stabilire il contesto della sessione o ripristinarlo. Per i contesti brevi, puoi inviare interazioni turn-by-turn per rappresentare la sequenza esatta di eventi. Per contesti più lunghi, è consigliabile fornire un riepilogo di un singolo messaggio per liberare la finestra contestuale per le interazioni successive.

Vedi il seguente messaggio di contesto di esempio:

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

Tieni presente che, sebbene le parti dei contenuti possano essere di tipo functionResponse, BidiGenerateContentClientContent non deve essere utilizzato per fornire una risposta alle chiamate di funzioni emesse dal modello. BidiGenerateContentToolResponse deve essere utilizzato invece. BidiGenerateContentClientContent deve essere utilizzato solo per stabilire il contesto precedente o fornire l'input di testo alla conversazione.

Streaming di audio e video

Esecuzione del codice

Per scoprire di più sull'esecuzione del codice, consulta Esecuzione del codice.

Chiamata di funzione

Tutte le funzioni devono essere dichiarate all'inizio della sessione inviando le definizioni degli strumenti come parte del messaggio BidiGenerateContentSetup.

Definisci le funzioni utilizzando JSON, in particolare con un sottoinsieme selezionato del formato dello schema OpenAPI. Una singola dichiarazione di funzione può includere i seguenti parametri:

• name (stringa): l'identificatore univoco della funzione all'interno della chiamata API.

• description (stringa): una spiegazione completa dello scopo e delle funzionalità della funzione.

• parametri (oggetto): definisce i dati di input richiesti dalla funzione.

  • type (stringa): specifica il tipo di dati complessivo, ad esempio object.

  • properties (oggetto): elenca i singoli parametri, ciascuno con:

    • type (stringa): il tipo di dati del parametro, ad esempio stringa, numero intero, booleano.
    • description (stringa): una spiegazione chiara dello scopo del parametro e del formato previsto.

  • required (array): un array di stringhe che elenca i nomi dei parametri obbligatori per il funzionamento della funzione.

Per esempi di codice di una dichiarazione di funzione che utilizza i comandi curl, vedi Chiamata di funzione con l'API Gemini. Per esempi di come creare dichiarazioni di funzioni utilizzando gli SDK dell'API Gemini, consulta l'esercitazione Chiamata di funzione.

Da un singolo prompt, il modello può generare più chiamate di funzione e il codice necessario per concatenare i relativi output. Questo codice viene eseguito in un ambiente sandbox, generando i successivi messaggi BidiGenerateContentToolCall. L'esecuzione viene sospesa finché non sono disponibili i risultati di ogni chiamata di funzione, il che garantisce l'elaborazione sequenziale.

Il cliente deve rispondere con BidiGenerateContentToolResponse.

Per saperne di più, consulta Introduzione alla chiamata di funzioni.

Formati audio

Consulta l'elenco dei formati audio supportati.

Istruzioni di sistema

Puoi fornire istruzioni di sistema per controllare meglio l'output del modello e specificare il tono e il sentimento delle risposte audio.

Le istruzioni di sistema vengono aggiunte al prompt prima dell'inizio dell'interazione e rimangono attive per l'intera sessione.

Le istruzioni di sistema possono essere impostate solo all'inizio di una sessione, subito dopo la connessione iniziale. Per fornire ulteriori input al modello durante la sessione, utilizza gli aggiornamenti incrementali dei contenuti.

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 scartata. Nella cronologia della sessione vengono conservate solo le informazioni già inviate al cliente. Il server quindi invia un messaggio BidiGenerateContentServerContent per segnalare l'interruzione.

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

Voci

Per specificare una voce, imposta voiceName all'interno dell'oggetto speechConfig, nell'ambito della configurazione della sessione.

Vedi la seguente rappresentazione JSON di un oggetto speechConfig:

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

Per visualizzare l'elenco delle voci supportate, consulta Modificare le impostazioni di voce e lingua.

Limitazioni

Quando pianifichi il tuo progetto, tieni presente le seguenti limitazioni dell'API Live e di Gemini 2.0.

Autenticazione client

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

Durata massima della sessione

La durata massima predefinita di una sessione di conversazione è di 10 minuti. Per maggiori informazioni, consulta Durata della sessione.

Rilevamento dell'attività vocale (VAD)

Per impostazione predefinita, il modello esegue automaticamente il rilevamento dell'attività vocale (VAD) su un flusso di input audio continuo. VAD può essere configurato con il campo RealtimeInputConfig.AutomaticActivityDetection del messaggio di configurazione.

Quando il flusso audio viene messo in pausa per più di un secondo (ad esempio, quando l'utente disattiva il microfono), viene inviato un evento AudioStreamEnd per svuotare l'audio memorizzato nella cache. Il client può riprendere l'invio dei dati audio in qualsiasi momento.

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. Invece, qualsiasi interruzione dello stream viene contrassegnata da un messaggio ActivityEnd.

Limitazioni aggiuntive

L'endpointing manuale non è supportato.

Gli input e gli output audio influiscono negativamente sulla capacità del modello di utilizzare la chiamata di funzioni.

Conteggio token

Il conteggio dei token non è supportato.

Limiti di frequenza

Si applicano i seguenti limiti di frequenza:

• 5000 sessioni simultanee per chiave API
• 4 milioni di token al minuto

Messaggi ed eventi

Passaggi successivi

• Scopri di più sulla chiamata di funzioni.
• Per esempi, consulta il riferimento alla chiamata di funzione.