Gemini 2.5 Pro Preview è ora disponibile per l'uso in produzione. Scopri di più

Questa pagina è stata tradotta dall'API Cloud Translation.

Live API - WebSockets API reference

L'API Live è un'API con stato che utilizza WebSockets. In questa sezione sono riportati ulteriori dettagli sull'API WebSockets.

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.

Connessione WebSocket

Per avviare una sessione, connettiti a questo endpoint WebSocket:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

Configurazione della sessione

Il messaggio iniziale dopo la connessione imposta la configurazione della sessione, che include il modello, i parametri di generazione, le istruzioni di sistema e gli strumenti.

Durante la sessione puoi modificare i parametri di configurazione, ad eccezione del modello.

Consulta la seguente configurazione di esempio. Tieni presente che le maiuscole dei nomi negli SDK possono variare. Puoi trovare le opzioni di configurazione dell'SDK Python qui.


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

Per ulteriori informazioni sul campo API, consulta generationConfig.

Inviare messaggi

Per scambiare messaggi tramite la connessione WebSocket, 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:

Messaggio	Descrizione
`BidiGenerateContentSetup`	Configurazione della sessione da inviare nel primo messaggio
`BidiGenerateContentClientContent`	Aggiornamento incrementale dei contenuti della conversazione corrente inviati dal client
`BidiGenerateContentRealtimeInput`	Input audio, video o di testo in tempo reale
`BidiGenerateContentToolResponse`	Risposta a un `ToolCallMessage` ricevuto dal server

Ricevere messaggi

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

Consulta quanto segue:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

I messaggi del server possono avere un campo usageMetadata, ma in caso contrario includeranno esattamente uno degli altri campi del messaggio BidiGenerateContentServerMessage. L'unione messageType non è espressa in JSON, pertanto il campo verrà visualizzato al primo livello del messaggio.

Messaggi ed eventi

ActivityEnd

Questo tipo non contiene campi.

Indica la fine dell'attività utente.

ActivityHandling

I diversi modi di gestire l'attività utente.

Enum
`ACTIVITY_HANDLING_UNSPECIFIED`	Se non specificato, il comportamento predefinito è `START_OF_ACTIVITY_INTERRUPTS`.
`START_OF_ACTIVITY_INTERRUPTS`	Se il valore è true, l'inizio dell'attività interrompe la risposta del modello (chiamato anche "interruzione"). La risposta corrente del modello verrà interrotta nel momento dell'interruzione. Questo è il comportamento predefinito.
`NO_INTERRUPTION`	La risposta del modello non verrà interrotta.

ActivityStart

Questo tipo non contiene campi.

Indica l'inizio dell'attività utente.

AudioTranscriptionConfig

Questo tipo non contiene campi.

La configurazione della trascrizione audio.

AutomaticActivityDetection

Configura il rilevamento automatico delle attività.

Campi
`disabled`	`bool` Facoltativo. Se è attivata (impostazione predefinita), l'input vocale e di testo rilevato viene conteggiato come attività. Se è disattivato, il client deve inviare indicatori di attività.
`startOfSpeechSensitivity`	`StartSensitivity` Facoltativo. Determina la probabilità che il parlato venga rilevato.
`prefixPaddingMs`	`int32` Facoltativo. La durata richiesta del parlato rilevato prima dell'inserimento dell'indicatore inizio parlato. Più basso è questo valore, più sensibile è il rilevamento dell'inizio del parlato e più breve può essere il parlato riconosciuto. Tuttavia, aumenta anche la probabilità di falsi positivi.
`endOfSpeechSensitivity`	`EndSensitivity` Facoltativo. Determina la probabilità che il parlato rilevato sia terminato.
`silenceDurationMs`	`int32` Facoltativo. La durata richiesta di parti non vocali rilevate (ad es. silenzio) prima che venga eseguito il commit del segnale di fine vocale. Maggiore è questo valore, più lunghi possono essere gli intervalli di parlato senza interrompere l'attività dell'utente, ma la latenza del modello aumenterà.

BidiGenerateContentClientContent

Aggiornamento incrementale della conversazione corrente inviata dal client. Tutti i contenuti qui presenti vengono aggiunti incondizionatamente alla cronologia delle conversazioni e utilizzati come parte del prompt per il modello per generare contenuti.

Un messaggio qui interromperà qualsiasi generazione di modelli in corso.

Campi

Campi
`turns[]`	`Content` Facoltativo. I contenuti aggiunti alla conversazione corrente con il modello. Per le query con un solo tratto, si tratta di una singola istanza. Per le query con più turni, si tratta di un campo ripetuto che contiene la cronologia della conversazione e l'ultima richiesta.
`turnComplete`	`bool` Facoltativo. Se true, indica che la generazione dei contenuti del server deve iniziare con il prompt attualmente accumulato. In caso contrario, il server attende altri messaggi prima di iniziare la generazione.

turns[]

Content

Facoltativo. I contenuti aggiunti alla conversazione corrente con il modello.

Per le query con un solo tratto, si tratta di una singola istanza. Per le query con più turni, si tratta di un campo ripetuto che contiene la cronologia della conversazione e l'ultima richiesta.

turnComplete

bool

Facoltativo. Se true, indica che la generazione dei contenuti del server deve iniziare con il prompt attualmente accumulato. In caso contrario, il server attende altri messaggi prima di iniziare la generazione.

BidiGenerateContentRealtimeInput

Input utente inviati in tempo reale.

Le diverse modalità (audio, video e testo) vengono gestite come stream simultanei. L'ordine in questi stream non è garantito.

È diverso da BidiGenerateContentClientContent in alcuni modi:

Possono essere inviati continuamente senza interruzioni per la generazione del modello.
Se è necessario combinare i dati interlacciati in BidiGenerateContentClientContent e BidiGenerateContentRealtimeInput, il server tenta di ottimizzare per la risposta migliore, ma non ci sono garanzie.
La fine del turno non è specificata esplicitamente, ma deriva dall'attività dell'utente (ad esempio, la fine del discorso).
Anche prima della fine del turno, i dati vengono elaborati in modo incrementale per ottimizzare l'avvio rapido della risposta del modello.

Campi
`mediaChunks[]`	`Blob` Facoltativo. Dati in linea in byte per l'input multimediale. Non sono supportati più `mediaChunks`, tutti tranne il primo verranno ignorati. DEPRECATO: utilizza uno dei valori `audio`, `video` o `text`.
`audio`	`Blob` Facoltativo. Questi formano lo stream di input audio in tempo reale.
`video`	`Blob` Facoltativo. Questi formano lo stream di input video in tempo reale.
`activityStart`	`ActivityStart` Facoltativo. Indica l'inizio dell'attività utente. Questo valore può essere inviato solo se il rilevamento automatico (ovvero lato server) dell'attività è disattivato.
`activityEnd`	`ActivityEnd` Facoltativo. Indica la fine dell'attività utente. Questo valore può essere inviato solo se il rilevamento automatico (ovvero lato server) dell'attività è disattivato.
`audioStreamEnd`	`bool` Facoltativo. Indica che lo stream audio è terminato, ad esempio perché il microfono è stato disattivato. Questo valore deve essere inviato solo quando è attivato il rilevamento automatico delle attività (impostazione predefinita). Il client può riaprire lo stream inviando un messaggio audio.
`text`	`string` Facoltativo. Questi formano lo stream di input di testo in tempo reale.

BidiGenerateContentServerContent

Aggiornamento incrementale del server generato dal modello in risposta ai messaggi del client.

I contenuti vengono generati il più rapidamente possibile e non in tempo reale. I client possono scegliere di mettere in buffer e riprodurre i contenuti in tempo reale.

Campi
`generationComplete`	`bool` Solo output. Se true, indica che la generazione del modello è stata completata. Quando il modello viene interrotto durante la generazione, non verrà visualizzato il messaggio "generation_complete" nel turno interrotto, ma verrà visualizzato "interrupted > turn_complete". Quando il modello presuppone la riproduzione in tempo reale, si verificherà un ritardo tra generation_complete e turn_complete causato dal fatto che il modello attende il termine della riproduzione.
`turnComplete`	`bool` Solo output. Se true, indica che il modello ha completato il suo turno. La generazione inizierà solo in risposta a ulteriori messaggi del client.
`interrupted`	`bool` Solo output. Se true, indica che un messaggio del client ha interrotto la generazione del modello corrente. Se il client riproduce i contenuti in tempo reale, è un buon segnale per interrompere e svuotare la coda di riproduzione corrente.
`groundingMetadata`	`GroundingMetadata` Solo output. Metadati di base per i contenuti generati.
`outputTranscription`	`BidiGenerateContentTranscription` Solo output. Consente di riprodurre la trascrizione audio. La trascrizione viene inviata indipendentemente dagli altri messaggi del server e non è garantito l'ordine, in particolare non tra `serverContent` e questo `outputTranscription`.
`modelTurn`	`Content` Solo output. I contenuti generati dal modello nell'ambito della conversazione in corso con l'utente.

BidiGenerateContentServerMessage

Messaggio di risposta per la chiamata BidiGenerateContent.

Campi
`usageMetadata`	`UsageMetadata` Solo output. Metadati di utilizzo relativi alle risposte.
Campo unione `messageType`. Il tipo di messaggio. `messageType` può essere solo uno dei seguenti:
`setupComplete`	`BidiGenerateContentSetupComplete` Solo output. Inviata in risposta a un messaggio `BidiGenerateContentSetup` del cliente al termine della configurazione.
`serverContent`	`BidiGenerateContentServerContent` Solo output. Contenuti generati dal modello in risposta ai messaggi del cliente.
`toolCall`	`BidiGenerateContentToolCall` Solo output. Chiedi al client di eseguire il `functionCalls` e di restituire le risposte con i `id` corrispondenti.
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` Solo output. Notifica al cliente che un `ToolCallMessage` emesso in precedenza con i `id` specificati deve essere annullato.
`goAway`	`GoAway` Solo output. Un avviso che indica che il server si disconnetterà a breve.
`sessionResumptionUpdate`	`SessionResumptionUpdate` Solo output. Aggiornamento dello stato di ripresa della sessione.

BidiGenerateContentSetup

Messaggio da inviare nel primo (e solo nel primo) BidiGenerateContentClientMessage. Contiene la configurazione che verrà applicata per la durata dell'RPC in streaming.

I client devono attendere un messaggio BidiGenerateContentSetupComplete prima di inviare altri messaggi.

Campi
`model`	`string` Obbligatorio. Il nome della risorsa del modello. che funge da ID per il modello. Formato: `models/{model}`
`generationConfig`	`GenerationConfig` Facoltativo. Configurazione della generazione. I seguenti campi non sono supportati: `responseLogprobs` `responseMimeType` `logprobs` `responseSchema` `stopSequence` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` Facoltativo. L'utente ha fornito le istruzioni di sistema per il modello. Nota: nelle parti deve essere utilizzato solo il testo e i contenuti di ogni parte saranno in un paragrafo separato.
`tools[]`	`Tool` Facoltativo. Un elenco di `Tools` che il modello potrebbe utilizzare per generare la risposta successiva. Un `Tool` è un frammento di codice che consente al sistema di interagire con sistemi esterni per eseguire un'azione o un insieme di azioni al di fuori della conoscenza e dell'ambito del modello.
`realtimeInputConfig`	`RealtimeInputConfig` Facoltativo. Configura la gestione dell'input in tempo reale.
`sessionResumption`	`SessionResumptionConfig` Facoltativo. Configura il meccanismo di ripresa della sessione. Se incluso, il server invierà messaggi `SessionResumptionUpdate`.
`contextWindowCompression`	`ContextWindowCompressionConfig` Facoltativo. Configura un meccanismo di compressione della finestra di contesto. Se incluso, il server ridurrà automaticamente le dimensioni del contesto quando supera la lunghezza configurata.
`outputAudioTranscription`	`AudioTranscriptionConfig` Facoltativo. Se impostato, attiva la trascrizione dell'output audio del modello. La trascrizione è in linea con il codice lingua specificato per l'audio di output, se configurato.

BidiGenerateContentSetupComplete

Questo tipo non contiene campi.

Inviato in risposta a un messaggio BidiGenerateContentSetup del cliente.

BidiGenerateContentToolCall

Chiedi al client di eseguire il functionCalls e di restituire le risposte con i id corrispondenti.

Campi

Campi
`functionCalls[]`	`FunctionCall` Solo output. La chiamata di funzione da eseguire.

functionCalls[]

FunctionCall

Solo output. La chiamata di funzione da eseguire.

BidiGenerateContentToolCallCancellation

Notifica al cliente che un ToolCallMessage emesso in precedenza con i id specificati non doveva essere eseguito e deve essere annullato. Se le chiamate allo strumento hanno avuto effetti collaterali, i client potrebbero tentare di annullarle. Questo messaggio si verifica solo nei casi in cui i client interrompono i turni del server.

Campi

Campi
`ids[]`	`string` Solo output. Gli ID delle chiamate dello strumento da annullare.

ids[]

string

Solo output. Gli ID delle chiamate dello strumento da annullare.

BidiGenerateContentToolResponse

Risposta generata dal client a un ToolCall ricevuto dal server. I singoli oggetti FunctionResponse vengono associati ai rispettivi oggetti FunctionCall in base al campo id.

Tieni presente che nelle API GenerateContent con streaming lato server e con un solo parametro la chiamata di funzione avviene scambiando le parti Content, mentre nelle API GenerateContent bidirezionali la chiamata di funzione avviene tramite questo insieme di messaggi dedicato.

Campi

Campi
`functionResponses[]`	`FunctionResponse` Facoltativo. La risposta alle chiamate di funzione.

functionResponses[]

FunctionResponse

Facoltativo. La risposta alle chiamate di funzione.

BidiGenerateContentTranscription

Trascrizione di audio (input o output).

Campi

Campi
`text`	`string` Testo della trascrizione.

text

string

Testo della trascrizione.

ContextWindowCompressionConfig

Attiva la compressione della finestra di contesto, un meccanismo per gestire la finestra di contesto del modello in modo che non superi una determinata lunghezza.

Campi

Campi
Campo unione `compressionMechanism`. Il meccanismo di compressione della finestra di contesto utilizzato. `compressionMechanism` può essere solo uno dei seguenti:
`slidingWindow`	`SlidingWindow` Un meccanismo a finestra mobile.
`triggerTokens`	`int64` Il numero di token (prima di eseguire un turno) necessari per attivare una compressione della finestra di contesto. Questo può essere utilizzato per bilanciare la qualità con la latenza, poiché finestre di contesto più brevi possono comportare risposte più rapide del modello. Tuttavia, qualsiasi operazione di compressione causerà un aumento temporaneo della latenza, pertanto non deve essere attivata di frequente. Se non viene impostato, il valore predefinito è l'80% del limite della finestra di contesto del modello. Rimane il 20% per la successiva richiesta dell'utente/risposta del modello.

Campo unione compressionMechanism. Il meccanismo di compressione della finestra di contesto utilizzato. compressionMechanism può essere solo uno dei seguenti:

slidingWindow

SlidingWindow

Un meccanismo a finestra mobile.

triggerTokens

int64

Il numero di token (prima di eseguire un turno) necessari per attivare una compressione della finestra di contesto.

Questo può essere utilizzato per bilanciare la qualità con la latenza, poiché finestre di contesto più brevi possono comportare risposte più rapide del modello. Tuttavia, qualsiasi operazione di compressione causerà un aumento temporaneo della latenza, pertanto non deve essere attivata di frequente.

Se non viene impostato, il valore predefinito è l'80% del limite della finestra di contesto del modello. Rimane il 20% per la successiva richiesta dell'utente/risposta del modello.

EndSensitivity

Determina in che modo viene rilevato il termine della conversazione.

Enum
`END_SENSITIVITY_UNSPECIFIED`	Il valore predefinito è END_SENSITIVITY_HIGH.
`END_SENSITIVITY_HIGH`	Il rilevamento automatico termina più spesso il parlato.
`END_SENSITIVITY_LOW`	Il rilevamento automatico termina il parlato meno spesso.

GoAway

Un avviso che indica che il server si disconnetterà a breve.

Campi

Campi
`timeLeft`	`Duration` Il tempo rimanente prima che la connessione venga interrotta come ABORTED. Questa durata non sarà mai inferiore a un valore minimo specifico del modello, che verrà specificato insieme ai limiti di frequenza per il modello.

timeLeft

Duration

Il tempo rimanente prima che la connessione venga interrotta come ABORTED.

Questa durata non sarà mai inferiore a un valore minimo specifico del modello, che verrà specificato insieme ai limiti di frequenza per il modello.

RealtimeInputConfig

Configura il comportamento di inserimento in tempo reale in BidiGenerateContent.

Campi

Campi
`automaticActivityDetection`	`AutomaticActivityDetection` Facoltativo. Se non è impostato, il rilevamento automatico delle attività è abilitato per impostazione predefinita. Se il rilevamento automatico della voce è disattivato, il cliente deve inviare indicatori di attività.
`activityHandling`	`ActivityHandling` Facoltativo. Definisce l'effetto dell'attività.
`turnCoverage`	`TurnCoverage` Facoltativo. Definisce quale input è incluso nel turno dell'utente.

automaticActivityDetection

AutomaticActivityDetection

Facoltativo. Se non è impostato, il rilevamento automatico delle attività è abilitato per impostazione predefinita. Se il rilevamento automatico della voce è disattivato, il cliente deve inviare indicatori di attività.

activityHandling

ActivityHandling

Facoltativo. Definisce l'effetto dell'attività.

turnCoverage

TurnCoverage

Facoltativo. Definisce quale input è incluso nel turno dell'utente.

SessionResumptionConfig

Configurazione della ripresa della sessione.

Questo messaggio è incluso nella configurazione della sessione come BidiGenerateContentSetup.sessionResumption. Se configurato, il server invierà messaggi SessionResumptionUpdate.

Campi

Campi
`handle`	`string` L'handle di una sessione precedente. In caso contrario, viene creata una nuova sessione. Gli handle delle sessioni provengono dai valori `SessionResumptionUpdate.token` nelle connessioni precedenti.

handle

string

L'handle di una sessione precedente. In caso contrario, viene creata una nuova sessione.

Gli handle delle sessioni provengono dai valori SessionResumptionUpdate.token nelle connessioni precedenti.

SessionResumptionUpdate

Aggiornamento dello stato di ripresa della sessione.

Viene inviato solo se è stato impostato BidiGenerateContentSetup.sessionResumption.

Campi

Campi
`newHandle`	`string` Nuovo handle che rappresenta uno stato che può essere ripreso. Vuoto se `resumable`=false.
`resumable`	`bool` True se la sessione corrente può essere ripresa in questo momento. La ripresa non è possibile in alcuni punti della sessione. Ad esempio, quando il modello esegue chiamate di funzioni o genera. La ripresa della sessione (utilizzando un token di sessione precedente) in questo stato comporterà una perdita di dati. In questi casi, `newHandle` sarà vuoto e `resumable` sarà falso.

newHandle

string

Nuovo handle che rappresenta uno stato che può essere ripreso. Vuoto se resumable=false.

resumable

bool

True se la sessione corrente può essere ripresa in questo momento.

La ripresa non è possibile in alcuni punti della sessione. Ad esempio, quando il modello esegue chiamate di funzioni o genera. La ripresa della sessione (utilizzando un token di sessione precedente) in questo stato comporterà una perdita di dati. In questi casi, newHandle sarà vuoto e resumable sarà falso.

SlidingWindow

Il metodo SlidingWindow opera ignorando i contenuti all'inizio della finestra di contesto. Il contesto risultante inizierà sempre all'inizio di un turno del ruolo USER. Le istruzioni di sistema e eventuali BidiGenerateContentSetup.prefixTurns rimarranno sempre all'inizio del risultato.

Campi

Campi
`targetTokens`	`int64` Il numero target di token da conservare. Il valore predefinito è trigger_tokens/2. L'eliminazione di parti della finestra di contesto causa un aumento temporaneo della latenza, pertanto questo valore deve essere calibrato per evitare frequenti operazioni di compressione.

targetTokens

int64

Il numero target di token da conservare. Il valore predefinito è trigger_tokens/2.

L'eliminazione di parti della finestra di contesto causa un aumento temporaneo della latenza, pertanto questo valore deve essere calibrato per evitare frequenti operazioni di compressione.

StartSensitivity

Determina in che modo viene rilevato l'inizio della voce.

Enum
`START_SENSITIVITY_UNSPECIFIED`	Il valore predefinito è START_SENSITIVITY_HIGH.
`START_SENSITIVITY_HIGH`	Il rilevamento automatico rileverà l'inizio della voce più spesso.
`START_SENSITIVITY_LOW`	Il rilevamento automatico rileverà l'inizio della voce meno spesso.

TurnCoverage

Opzioni relative all'input incluso nel turno dell'utente.

Enum
`TURN_COVERAGE_UNSPECIFIED`	Se non specificato, il comportamento predefinito è `TURN_INCLUDES_ONLY_ACTIVITY`.
`TURN_INCLUDES_ONLY_ACTIVITY`	Il turno dell'utente include solo le attività dall'ultimo turno, esclusa l'inattività (ad es. il silenzio nello stream audio). Questo è il comportamento predefinito.
`TURN_INCLUDES_ALL_INPUT`	Il turno dell'utente include tutti gli input in tempo reale dall'ultimo turno, inclusa l'inattività (ad es. silenzio nello stream audio).

UsageMetadata

Metadati di utilizzo relativi alle risposte.

Campi
`promptTokenCount`	`int32` Solo output. Numero di token nel prompt. Quando è impostato `cachedContent`, si tratta comunque della dimensione effettiva totale del prompt, ovvero è incluso il numero di token nei contenuti memorizzati nella cache.
`cachedContentTokenCount`	`int32` Numero di token nella parte memorizzata nella cache del prompt (i contenuti memorizzati nella cache)
`responseTokenCount`	`int32` Solo output. Numero totale di token in tutte le risposte candidate generate.
`toolUsePromptTokenCount`	`int32` Solo output. Numero di token presenti nei prompt per l'utilizzo dello strumento.
`thoughtsTokenCount`	`int32` Solo output. Numero di token di pensieri per i modelli di pensiero.
`totalTokenCount`	`int32` Solo output. Numero totale di token per la richiesta di generazione (prompt + candidati per la risposta).
`promptTokensDetails[]`	`ModalityTokenCount` Solo output. Elenco delle modalità elaborate nell'input della richiesta.
`cacheTokensDetails[]`	`ModalityTokenCount` Solo output. Elenco delle modalità dei contenuti memorizzati nella cache nell'input della richiesta.
`responseTokensDetails[]`	`ModalityTokenCount` Solo output. Elenco delle modalità restituite nella risposta.
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` Solo output. Elenco delle modalità elaborate per gli input delle richieste di utilizzo dello strumento.

Ulteriori informazioni sui tipi comuni

Per saperne di più sui tipi di risorse API di uso comune Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount e Tool, consulta Generare contenuti.