A prévia do Gemini 2.5 Pro já está disponível para uso na produção. Saiba mais

Esta página foi traduzida pela API Cloud Translation.

Live API - WebSockets API reference

A API Live é uma API stateful que usa WebSockets. Nesta seção, você vai encontrar mais detalhes sobre a API WebSockets.

Sessões

Uma conexão WebSocket estabelece uma sessão entre o cliente e o servidor Gemini. Depois que um cliente inicia uma nova conexão, a sessão pode trocar mensagens com o servidor para:

Enviar texto, áudio ou vídeo para o servidor do Gemini.
Receber solicitações de chamada de áudio, texto ou função do servidor do Gemini.

Conexão WebSocket

Para iniciar uma sessão, conecte-se a este endpoint do WebSocket:

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

Configuração da sessão

A mensagem inicial após a conexão define a configuração da sessão, que inclui o modelo, os parâmetros de geração, as instruções do sistema e as ferramentas.

É possível mudar os parâmetros de configuração, exceto o modelo, durante a sessão.

Confira o exemplo de configuração a seguir. O uso de maiúsculas e minúsculas nos SDKs pode variar. Consulte as opções de configuração do SDK do Python aqui.


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

Para mais informações sobre o campo da API, consulte generationConfig.

Enviar mensagens

Para trocar mensagens pela conexão WebSocket, o cliente precisa enviar um objeto JSON por uma conexão WebSocket aberta. O objeto JSON precisa ter exatamente um dos campos do seguinte conjunto de objetos:


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

Mensagens de cliente com suporte

Confira as mensagens de cliente compatíveis na tabela a seguir:

Mensagem	Descrição
`BidiGenerateContentSetup`	Configuração da sessão a ser enviada na primeira mensagem
`BidiGenerateContentClientContent`	Atualização incremental do conteúdo da conversa atual enviada pelo cliente
`BidiGenerateContentRealtimeInput`	Entrada de áudio, vídeo ou texto em tempo real
`BidiGenerateContentToolResponse`	Resposta a uma `ToolCallMessage` recebida do servidor

Receber mensagens

Para receber mensagens do Gemini, detecte o evento "message" do WebSocket e analise o resultado de acordo com a definição das mensagens do servidor com suporte.

Confira estes guias:

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)

As mensagens do servidor podem ter um campo usageMetadata, mas incluem exatamente um dos outros campos da mensagem BidiGenerateContentServerMessage. A união messageType não é expressa em JSON, portanto, o campo vai aparecer no nível superior da mensagem.

Mensagens e eventos

ActivityEnd

Esse tipo não tem campos.

Marca o fim da atividade do usuário.

ActivityHandling

As diferentes maneiras de lidar com a atividade do usuário.

Enums
`ACTIVITY_HANDLING_UNSPECIFIED`	Se não for especificado, o comportamento padrão será `START_OF_ACTIVITY_INTERRUPTS`.
`START_OF_ACTIVITY_INTERRUPTS`	Se for verdadeiro, o início da atividade vai interromper a resposta do modelo, também chamada de "invasão". A resposta atual do modelo será interrompida no momento da interrupção. Esse é o comportamento padrão.
`NO_INTERRUPTION`	A resposta do modelo não será interrompida.

ActivityStart

Esse tipo não tem campos.

Marca o início da atividade do usuário.

AudioTranscriptionConfig

Esse tipo não tem campos.

A configuração da transcrição de áudio.

AutomaticActivityDetection

Configura a detecção automática de atividade.

Campos
`disabled`	`bool` Opcional. Se ativada (padrão), a entrada de voz e texto detectada é considerada uma atividade. Se desativado, o cliente precisa enviar indicadores de atividade.
`startOfSpeechSensitivity`	`StartSensitivity` Opcional. Determina a probabilidade de detecção da fala.
`prefixPaddingMs`	`int32` Opcional. A duração necessária da fala detectada antes que o início da fala seja confirmado. Quanto menor esse valor, mais sensível será a detecção do início da fala e mais curtos poderão ser os discursos reconhecidos. No entanto, isso também aumenta a probabilidade de falsos positivos.
`endOfSpeechSensitivity`	`EndSensitivity` Opcional. Determina a probabilidade de a fala detectada ter terminado.
`silenceDurationMs`	`int32` Opcional. A duração necessária de não fala detectada (por exemplo, silêncio) antes do fim da fala. Quanto maior esse valor, mais longos podem ser os intervalos de fala sem interromper a atividade do usuário, mas isso aumenta a latência do modelo.

BidiGenerateContentClientContent

Atualização incremental da conversa atual enviada pelo cliente. Todo o conteúdo aqui é adicionado incondicionalmente ao histórico de conversas e usado como parte do comando para o modelo gerar conteúdo.

Uma mensagem aqui vai interromper qualquer geração de modelo atual.

Campos

Campos
`turns[]`	`Content` Opcional. O conteúdo anexado à conversa atual com o modelo. Para consultas de turno único, esta é uma instância única. Para consultas com várias interações, esse é um campo repetido que contém o histórico da conversa e a solicitação mais recente.
`turnComplete`	`bool` Opcional. Se verdadeiro, indica que a geração de conteúdo do servidor precisa começar com o comando acumulado. Caso contrário, o servidor aguarda outras mensagens antes de iniciar a geração.

turns[]

Content

Opcional. O conteúdo anexado à conversa atual com o modelo.

Para consultas de turno único, esta é uma instância única. Para consultas com várias interações, esse é um campo repetido que contém o histórico da conversa e a solicitação mais recente.

turnComplete

bool

Opcional. Se verdadeiro, indica que a geração de conteúdo do servidor precisa começar com o comando acumulado. Caso contrário, o servidor aguarda outras mensagens antes de iniciar a geração.

BidiGenerateContentRealtimeInput

Entrada do usuário enviada em tempo real.

As diferentes modalidades (áudio, vídeo e texto) são tratadas como streams simultâneos. A ordem desses fluxos não é garantida.

Isso é diferente de BidiGenerateContentClientContent de algumas maneiras:

Podem ser enviados continuamente sem interrupção para a geração de modelos.
Se for necessário misturar dados intercalados entre BidiGenerateContentClientContent e BidiGenerateContentRealtimeInput, o servidor vai tentar otimizar a melhor resposta, mas não há garantias.
O fim da vez não é especificado explicitamente, mas é derivado da atividade do usuário (por exemplo, fim da fala).
Mesmo antes do fim da jogada, os dados são processados de forma incremental para otimizar o início rápido da resposta do modelo.

Campos
`mediaChunks[]`	`Blob` Opcional. Dados de bytes inline para entrada de mídia. Não há suporte para vários `mediaChunks`. Todos, exceto o primeiro, serão ignorados. OBSOLETO: use `audio`, `video` ou `text`.
`audio`	`Blob` Opcional. Eles formam o stream de entrada de áudio em tempo real.
`video`	`Blob` Opcional. Eles formam o fluxo de entrada de vídeo em tempo real.
`activityStart`	`ActivityStart` Opcional. Marca o início da atividade do usuário. Isso só pode ser enviado se a detecção automática (ou seja, do lado do servidor) estiver desativada.
`activityEnd`	`ActivityEnd` Opcional. Marca o fim da atividade do usuário. Isso só pode ser enviado se a detecção automática (ou seja, do lado do servidor) estiver desativada.
`audioStreamEnd`	`bool` Opcional. Indica que o fluxo de áudio foi encerrado, por exemplo, porque o microfone foi desativado. Ele só é enviado quando a detecção automática de atividades está ativada, o que é o padrão. O cliente pode reabrir o stream enviando uma mensagem de áudio.
`text`	`string` Opcional. Eles formam o fluxo de entrada de texto em tempo real.

BidiGenerateContentServerContent

Atualização incremental do servidor gerada pelo modelo em resposta às mensagens do cliente.

O conteúdo é gerado o mais rápido possível, e não em tempo real. Os clientes podem escolher armazenar em buffer e reproduzir em tempo real.

Campos
`generationComplete`	`bool` Apenas saída. Se verdadeiro, indica que a geração do modelo foi concluída. Quando o modelo é interrompido durante a geração, não há a mensagem "generation_complete" na jogada interrompida. Ela passa por "interrupted > turn_complete". Quando o modelo assume a reprodução em tempo real, há um atraso entre generation_complete e turn_complete causado pelo modelo que aguarda a conclusão da reprodução.
`turnComplete`	`bool` Apenas saída. Se verdadeiro, indica que o modelo concluiu a vez. A geração só vai começar em resposta a outras mensagens do cliente.
`interrupted`	`bool` Apenas saída. Se verdadeiro, indica que uma mensagem do cliente interrompeu a geração de modelos atual. Se o cliente estiver reproduzindo o conteúdo em tempo real, esse é um bom sinal para interromper e esvaziar a fila de reprodução atual.
`groundingMetadata`	`GroundingMetadata` Apenas saída. Agrupar metadados para o conteúdo gerado.
`outputTranscription`	`BidiGenerateContentTranscription` Apenas saída. Gera uma transcrição de áudio. A transcrição é enviada independentemente das outras mensagens do servidor, e não há ordem garantida, principalmente entre `serverContent` e `outputTranscription`.
`modelTurn`	`Content` Apenas saída. O conteúdo que o modelo gerou como parte da conversa atual com o usuário.

BidiGenerateContentServerMessage

Mensagem de resposta para a chamada BidiGenerateContent.

Campos
`usageMetadata`	`UsageMetadata` Apenas saída. Metadados de uso sobre as respostas.
Campo de união `messageType`. Tipo da mensagem. `messageType` pode ser apenas de um dos tipos a seguir:
`setupComplete`	`BidiGenerateContentSetupComplete` Apenas saída. Enviada em resposta a uma mensagem `BidiGenerateContentSetup` do cliente quando a configuração é concluída.
`serverContent`	`BidiGenerateContentServerContent` Apenas saída. Conteúdo gerado pelo modelo em resposta às mensagens do cliente.
`toolCall`	`BidiGenerateContentToolCall` Apenas saída. Solicitar que o cliente execute o `functionCalls` e retorne as respostas com os `id`s correspondentes.
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` Apenas saída. Notificação ao cliente de que um `ToolCallMessage` emitido anteriormente com os `id`s especificados precisa ser cancelado.
`goAway`	`GoAway` Apenas saída. Uma notificação de que o servidor será desconectado em breve.
`sessionResumptionUpdate`	`SessionResumptionUpdate` Apenas saída. Atualização do estado de retomada da sessão.

BidiGenerateContentSetup

Mensagem a ser enviada na primeira (e somente na primeira) BidiGenerateContentClientMessage. Contém a configuração que será aplicada durante a duração do RPC de streaming.

Os clientes precisam aguardar uma mensagem BidiGenerateContentSetupComplete antes de enviar outras mensagens.

Campos
`model`	`string` Obrigatório. O nome do recurso do modelo. Ele serve como um ID para o modelo usar. Formato: `models/{model}`
`generationConfig`	`GenerationConfig` Opcional. Configuração de geração. Os seguintes campos não são aceitos: `responseLogprobs` `responseMimeType` `logprobs` `responseSchema` `stopSequence` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` Opcional. O usuário forneceu instruções do sistema para o modelo. Observação: use apenas texto em partes, e o conteúdo de cada parte ficará em um parágrafo separado.
`tools[]`	`Tool` Opcional. Uma lista de `Tools` que o modelo pode usar para gerar a próxima resposta. Um `Tool` é um código que permite ao sistema interagir com sistemas externos para realizar uma ação ou conjunto de ações fora do conhecimento e do escopo do modelo.
`realtimeInputConfig`	`RealtimeInputConfig` Opcional. Configura o processamento de entrada em tempo real.
`sessionResumption`	`SessionResumptionConfig` Opcional. Configura o mecanismo de retomada da sessão. Se incluído, o servidor vai enviar mensagens `SessionResumptionUpdate`.
`contextWindowCompression`	`ContextWindowCompressionConfig` Opcional. Configura um mecanismo de compactação de janela de contexto. Se incluído, o servidor vai reduzir automaticamente o tamanho do contexto quando ele exceder o comprimento configurado.
`outputAudioTranscription`	`AudioTranscriptionConfig` Opcional. Se definido, ativa a transcrição da saída de áudio do modelo. A transcrição é alinhada com o código de idioma especificado para o áudio de saída, se configurado.

BidiGenerateContentSetupComplete

Esse tipo não tem campos.

Enviada em resposta a uma mensagem BidiGenerateContentSetup do cliente.

BidiGenerateContentToolCall

Solicitar que o cliente execute o functionCalls e retorne as respostas com os ids correspondentes.

Campos

Campos
`functionCalls[]`	`FunctionCall` Apenas saída. A chamada de função a ser executada.

functionCalls[]

FunctionCall

Apenas saída. A chamada de função a ser executada.

BidiGenerateContentToolCallCancellation

Notificação ao cliente de que um ToolCallMessage emitido anteriormente com os ids especificados não deveria ter sido executado e precisa ser cancelado. Se houver efeitos colaterais nessas chamadas de ferramentas, os clientes poderão tentar desfazer as chamadas. Essa mensagem ocorre apenas nos casos em que os clientes interrompem as rodadas do servidor.

Campos

Campos
`ids[]`	`string` Apenas saída. Os IDs das chamadas de ferramenta a serem canceladas.

ids[]

string

Apenas saída. Os IDs das chamadas de ferramenta a serem canceladas.

BidiGenerateContentToolResponse

Resposta gerada pelo cliente para uma ToolCall recebida do servidor. Os objetos FunctionResponse individuais são associados aos respectivos objetos FunctionCall pelo campo id.

Nas APIs unary e de streaming do servidor, a chamada de função GenerateContent acontece trocando as partes Content, enquanto nas APIs bidi, a chamada de função acontece sobre esse conjunto dedicado de mensagens.

Campos

Campos
`functionResponses[]`	`FunctionResponse` Opcional. A resposta às chamadas de função.

functionResponses[]

FunctionResponse

Opcional. A resposta às chamadas de função.

BidiGenerateContentTranscription

Transcrição de áudio (entrada ou saída).

Campos

Campos
`text`	`string` Texto da transcrição.

text

string

Texto da transcrição.

ContextWindowCompressionConfig

Ativa a compactação da janela de contexto, um mecanismo para gerenciar a janela de contexto do modelo para que ela não exceda um determinado comprimento.

Campos

Campos
Campo de união `compressionMechanism`. O mecanismo de compactação da janela de contexto usado. `compressionMechanism` pode ser apenas de um dos tipos a seguir:
`slidingWindow`	`SlidingWindow` Um mecanismo de janela deslizante.
`triggerTokens`	`int64` O número de tokens (antes de executar uma jogada) necessários para acionar uma compactação da janela de contexto. Isso pode ser usado para equilibrar a qualidade com a latência, já que janelas de contexto mais curtas podem resultar em respostas mais rápidas do modelo. No entanto, qualquer operação de compactação causa um aumento temporário da latência. Por isso, elas não devem ser acionadas com frequência. Se não for definido, o padrão será 80% do limite da janela de contexto do modelo. Isso deixa 20% para a próxima solicitação do usuário/resposta do modelo.

Campo de união compressionMechanism. O mecanismo de compactação da janela de contexto usado. compressionMechanism pode ser apenas de um dos tipos a seguir:

slidingWindow

SlidingWindow

Um mecanismo de janela deslizante.

triggerTokens

int64

O número de tokens (antes de executar uma jogada) necessários para acionar uma compactação da janela de contexto.

Isso pode ser usado para equilibrar a qualidade com a latência, já que janelas de contexto mais curtas podem resultar em respostas mais rápidas do modelo. No entanto, qualquer operação de compactação causa um aumento temporário da latência. Por isso, elas não devem ser acionadas com frequência.

Se não for definido, o padrão será 80% do limite da janela de contexto do modelo. Isso deixa 20% para a próxima solicitação do usuário/resposta do modelo.

EndSensitivity

Determina como o fim da fala é detectado.

Enums
`END_SENSITIVITY_UNSPECIFIED`	O padrão é END_SENSITIVITY_HIGH.
`END_SENSITIVITY_HIGH`	A detecção automática encerra a fala com mais frequência.
`END_SENSITIVITY_LOW`	A detecção automática encerra a fala com menos frequência.

GoAway

Uma notificação de que o servidor será desconectado em breve.

Campos

Campos
`timeLeft`	`Duration` O tempo restante antes que a conexão seja encerrada como CANCELADA. Essa duração nunca será menor que o mínimo específico do modelo, que será especificado junto com os limites de taxa do modelo.

timeLeft

Duration

O tempo restante antes que a conexão seja encerrada como CANCELADA.

Essa duração nunca será menor que o mínimo específico do modelo, que será especificado junto com os limites de taxa do modelo.

RealtimeInputConfig

Configura o comportamento de entrada em tempo real em BidiGenerateContent.

Campos

Campos
`automaticActivityDetection`	`AutomaticActivityDetection` Opcional. Se não for definido, a detecção automática de atividades será ativada por padrão. Se a detecção automática de voz estiver desativada, o cliente precisará enviar indicadores de atividade.
`activityHandling`	`ActivityHandling` Opcional. Define o efeito da atividade.
`turnCoverage`	`TurnCoverage` Opcional. Define qual entrada é incluída na vez do usuário.

automaticActivityDetection

AutomaticActivityDetection

Opcional. Se não for definido, a detecção automática de atividades será ativada por padrão. Se a detecção automática de voz estiver desativada, o cliente precisará enviar indicadores de atividade.

activityHandling

ActivityHandling

Opcional. Define o efeito da atividade.

turnCoverage

TurnCoverage

Opcional. Define qual entrada é incluída na vez do usuário.

SessionResumptionConfig

Configuração de retomada da sessão.

Essa mensagem é incluída na configuração da sessão como BidiGenerateContentSetup.sessionResumption. Se configurado, o servidor vai enviar mensagens SessionResumptionUpdate.

Campos

Campos
`handle`	`string` O identificador de uma sessão anterior. Se não estiver presente, uma nova sessão será criada. Os identificadores de sessão vêm de valores `SessionResumptionUpdate.token` em conexões anteriores.

handle

string

O identificador de uma sessão anterior. Se não estiver presente, uma nova sessão será criada.

Os identificadores de sessão vêm de valores SessionResumptionUpdate.token em conexões anteriores.

SessionResumptionUpdate

Atualização do estado de retomada da sessão.

Só é enviado se BidiGenerateContentSetup.sessionResumption foi definido.

Campos

Campos
`newHandle`	`string` Novo identificador que representa um estado que pode ser retomado. Vazio se `resumable`=false.
`resumable`	`bool` Verdadeiro se a sessão atual puder ser retomada neste ponto. Não é possível retomar a sessão em alguns pontos. Por exemplo, quando o modelo está executando ou gerando chamadas de função. Retomar a sessão (usando um token de sessão anterior) nesse estado resultará em perda de dados. Nesses casos, `newHandle` vai estar vazio e `resumable` será falso.

newHandle

string

Novo identificador que representa um estado que pode ser retomado. Vazio se resumable=false.

resumable

bool

Verdadeiro se a sessão atual puder ser retomada neste ponto.

Não é possível retomar a sessão em alguns pontos. Por exemplo, quando o modelo está executando ou gerando chamadas de função. Retomar a sessão (usando um token de sessão anterior) nesse estado resultará em perda de dados. Nesses casos, newHandle vai estar vazio e resumable será falso.

SlidingWindow

O método SlidingWindow opera descartando o conteúdo no início da janela de contexto. O contexto resultante sempre começa no início de uma rodada de função de USUÁRIO. As instruções do sistema e qualquer BidiGenerateContentSetup.prefixTurns sempre vão permanecer no início do resultado.

Campos

Campos
`targetTokens`	`int64` O número de tokens a serem mantidos. O valor padrão é trigger_tokens/2. O descarte de partes da janela de contexto causa um aumento temporário da latência. Portanto, esse valor precisa ser calibrado para evitar operações de compactação frequentes.

targetTokens

int64

O número de tokens a serem mantidos. O valor padrão é trigger_tokens/2.

O descarte de partes da janela de contexto causa um aumento temporário da latência. Portanto, esse valor precisa ser calibrado para evitar operações de compactação frequentes.

StartSensitivity

Determina como o início da fala é detectado.

Enums
`START_SENSITIVITY_UNSPECIFIED`	O padrão é START_SENSITIVITY_HIGH.
`START_SENSITIVITY_HIGH`	A detecção automática vai detectar o início da fala com mais frequência.
`START_SENSITIVITY_LOW`	A detecção automática vai detectar o início da fala com menos frequência.

TurnCoverage

Opções sobre qual entrada é incluída na vez do usuário.

Enums
`TURN_COVERAGE_UNSPECIFIED`	Se não for especificado, o comportamento padrão será `TURN_INCLUDES_ONLY_ACTIVITY`.
`TURN_INCLUDES_ONLY_ACTIVITY`	A vez do usuário inclui apenas a atividade desde a última vez, excluindo a inatividade (por exemplo, silêncio no stream de áudio). Esse é o comportamento padrão.
`TURN_INCLUDES_ALL_INPUT`	A vez do usuário inclui todas as entradas em tempo real desde a última vez, incluindo a inatividade (por exemplo, silêncio no fluxo de áudio).

UsageMetadata

Metadados de uso sobre as respostas.

Campos
`promptTokenCount`	`int32` Apenas saída. Número de tokens no comando. Quando `cachedContent` é definido, ele ainda é o tamanho total do comando eficaz, o que significa que inclui o número de tokens no conteúdo armazenado em cache.
`cachedContentTokenCount`	`int32` Número de tokens na parte armazenada em cache do comando (o conteúdo armazenado em cache)
`responseTokenCount`	`int32` Apenas saída. Número total de tokens em todos os candidatos de resposta gerados.
`toolUsePromptTokenCount`	`int32` Apenas saída. Número de tokens presentes nas solicitações de uso da ferramenta.
`thoughtsTokenCount`	`int32` Apenas saída. Número de tokens de pensamentos para modelos de pensamento.
`totalTokenCount`	`int32` Apenas saída. Contagem total de tokens para a solicitação de geração (comando + candidatos de resposta).
`promptTokensDetails[]`	`ModalityTokenCount` Apenas saída. Lista de modalidades processadas na entrada da solicitação.
`cacheTokensDetails[]`	`ModalityTokenCount` Apenas saída. Lista de modalidades do conteúdo em cache na entrada da solicitação.
`responseTokensDetails[]`	`ModalityTokenCount` Apenas saída. Lista de modalidades que foram retornadas na resposta.
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` Apenas saída. Lista de modalidades processadas para entradas de solicitação de uso da ferramenta.

Mais informações sobre tipos comuns

Para mais informações sobre os tipos de recurso de API mais usados Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount e Tool, consulte Como gerar conteúdo.