Riferimento API Live

L'API Live consente interazioni vocali e video bidirezionali a bassa latenza con Gemini. Con 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 ulteriori informazioni sull'API Live, consulta 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 di sessione: il modello conserva la memoria di tutte le interazioni all'interno di un'unica sessione, richiamando le informazioni ascoltate o viste in precedenza.
• Supporto per la chiamata di funzioni, l'esecuzione di codice e la Ricerca come strumento: puoi integrare il modello con servizi e origini dati esterni.

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

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

Modelli supportati

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 in testo utilizzando Python 3.9 e versioni successive.

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 ha avviato una nuova connessione, la sessione può scambiare messaggi con il server per:

• Invia testo, audio o video al server Gemini.
• Ricevere richieste di chiamate audio, di testo o di funzione 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 ulteriori 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 avere esattamente uno dei campi del seguente insieme di oggetti:

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

Messaggi client supportati

Consulta i messaggi client supportati nella tabella seguente:

Ricevere messaggi

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

Consulta 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 insieme 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 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. Per contesti più lunghi, è consigliabile fornire un riepilogo di un singolo messaggio per liberare la finestra di contesto per le interazioni successive.

Vedi il seguente esempio di messaggio contestuale:

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

Tieni presente che, anche se le parti di contenuto possono essere di tipo functionResponse, BidiGenerateContentClientContent non deve essere utilizzato per fornire una risposta alle chiamate di funzione emesse dal modello. Dovresti utilizzare BidiGenerateContentToolResponse. BidiGenerateContentClientContent deve essere utilizzato solo per stabilire il contesto precedente o fornire input di testo alla conversazione.

Riproduzione in 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.

Le funzioni vengono definite 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 scopo e funzionalità della funzione.

• parameters (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, come stringa, numero intero, booleano.
    • description (stringa): una spiegazione chiara dello scopo e del formato previsto del parametro.

  • 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, consulta Chiamata di funzione con l'API Gemini. Per esempi su come creare dichiarazioni di funzioni utilizzando gli SDK dell'API Gemini, consulta il tutorial sulle chiamate di funzione.

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. 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.

Il cliente deve rispondere con BidiGenerateContentToolResponse.

Per scoprire di più, consulta Introduzione alle chiamate 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 sentiment delle risposte audio.

Le istruzioni di sistema vengono aggiunte al prompt prima dell'inizio dell'interazione e rimangono in vigore 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 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 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, come parte della configurazione della sessione.

Consulta 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 lingua e voce.

Limitazioni

Tieni presente le seguenti limitazioni dell'API Live e di Gemini 2.0 quando pianifichi il tuo progetto.

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 massima della sessione

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

Rilevamento attività vocale (VAD)

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

Quando lo stream 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 la cache dell'audio. Il client può riprendere l'invio di dati audio in qualsiasi momento.

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.

Limitazioni aggiuntive

L'endpointing manuale non è supportato.

Gli input e gli output audio influiscono negativamente sulla capacità del modello di utilizzare le chiamate di funzione.

Conteggio token

Il conteggio dei token non è supportato.

Limiti di frequenza

Si applicano i seguenti limiti di frequenza:

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

Messaggi ed eventi

Passaggi successivi

• Scopri di più sulle chiamate di funzione.
• Per esempi, consulta la documentazione di riferimento per le chiamate di funzione.