Referência da API em tempo real

A API Live permite interações de voz e vídeo bidirecionais de baixa latência com o Gemini. Com a API Live, é possível oferecer aos usuários finais a experiência de conversas naturais e semelhantes às humanas, além da capacidade de interromper as respostas do modelo usando comandos de voz. A API Live pode processar entradas de texto, áudio e vídeo, além de fornecer saídas de texto e áudio.

Para mais informações sobre a API Live, consulte API Live.

Recursos

A API Live inclui os seguintes recursos principais:

• Multimodalidade: o modelo pode ver, ouvir e falar.
• Interação em tempo real com baixa latência: o modelo pode fornecer respostas rápidas.
• Memória da sessão: o modelo retém a memória de todas as interações em uma única sessão, lembrando informações ouvidas ou vistas anteriormente.
• Suporte para chamadas de função, execução de código e Pesquisa como uma ferramenta: é possível integrar o modelo a serviços e fontes de dados externos.

A API Live foi criada para comunicação de servidor para servidor.

Para apps da Web e para dispositivos móveis, recomendamos usar a integração dos nossos parceiros na Daily.

Modelos compatíveis

• Gemini 2.5 Flash com áudio nativo da API Live
  previewPré-lançamento
• Gemini 2.0 Flash com API Live
  previewpré-lançamento
• Gemini 2.5 Flash

Primeiros passos

Para testar a API Live, acesse o Vertex AI Studio e clique em Iniciar sessão.

A API Live é uma API com estado que usa WebSockets.

Esta seção mostra um exemplo de como usar a API Live para geração de texto para texto usando 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?

Guia de integração

Esta seção descreve como a integração funciona com a API Live.

Sessões

Uma conexão WebSocket estabelece uma sessão entre o cliente e o servidor do 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 áudio, texto ou chamada de função do servidor do Gemini.

A configuração da sessão é enviada na primeira mensagem após a conexão. Uma configuração de sessão inclui o modelo, os parâmetros de geração, as instruções do sistema e as ferramentas.

Confira o exemplo de configuração a seguir:

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

Para mais informações, consulte BidiGenerateContentSetup.

Enviar mensagens

As mensagens são objetos formatados em JSON trocados pela conexão WebSocket.

Para enviar uma mensagem, 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 clientes compatíveis

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

Receber mensagens

Para receber mensagens do Gemini, fique atento ao evento "message" do WebSocket e analise o resultado de acordo com a definição das mensagens compatíveis do servidor.

Confira a seguir:

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

As mensagens do servidor terão exatamente um dos campos do seguinte conjunto de objetos:

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

Mensagens do servidor compatíveis

Confira os tipos de mensagens do servidor compatíveis na tabela a seguir:

Atualizações incrementais de conteúdo

Use atualizações incrementais para enviar entrada de texto, estabelecer ou restaurar o contexto da sessão. Para contextos curtos, você pode enviar interações de turno a turno para representar a sequência exata de eventos. Para contextos mais longos, é recomendável fornecer um único resumo da mensagem para liberar a janela de contexto para as interações de acompanhamento.

Confira o exemplo de mensagem de contexto a seguir:

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

Embora as partes de conteúdo possam ser do tipo functionResponse, BidiGenerateContentClientContent não deve ser usado para fornecer uma resposta às chamadas de função emitidas pelo modelo. Use BidiGenerateContentToolResponse. BidiGenerateContentClientContent só deve ser usado para estabelecer um contexto anterior ou fornecer entrada de texto para a conversa.

Streaming de áudio e vídeo

Execução de código

Para saber mais sobre a execução de código, consulte Execução de código.

Chamadas de função

Todas as funções precisam ser declaradas no início da sessão enviando definições de ferramentas como parte da mensagem BidiGenerateContentSetup.

Você define funções usando JSON, especificamente com um subconjunto selecionado do formato de esquema OpenAPI. Uma única declaração de função pode incluir os seguintes parâmetros:

• name (string): o identificador exclusivo da função na chamada de API.

• description (string): uma explicação abrangente do propósito e das capacidades da função.

• parameters (objeto): define os dados de entrada necessários para a função.

  • type (string): especifica o tipo de dados geral, como objeto.

  • properties (objeto): lista parâmetros individuais, cada um com:

    • type (string): o tipo de dados do parâmetro, como string, número inteiro, booleano.
    • description (string): uma explicação clara da finalidade e do formato esperado do parâmetro.

  • required (matriz): uma matriz de strings que lista os nomes dos parâmetros obrigatórios para o funcionamento da função.

Para exemplos de código de uma declaração de função usando comandos curl, consulte Chamada de função com a API Gemini. Para exemplos de como criar declarações de função usando os SDKs da API Gemini, consulte o tutorial de chamada de função.

Com um único comando, o modelo pode gerar várias chamadas de função e o código necessário para encadear as saídas. Esse código é executado em um ambiente de sandbox, gerando mensagens BidiGenerateContentToolCall subsequentes. A execução é pausada até que os resultados de cada chamada de função estejam disponíveis, o que garante o processamento sequencial.

O cliente deve responder com BidiGenerateContentToolResponse.

Para saber mais, consulte Introdução à chamada de função.

Formatos de áudio

Consulte a lista de formatos de áudio compatíveis.

Instruções do sistema

É possível fornecer instruções do sistema para controlar melhor a saída do modelo e especificar o tom e o sentimento das respostas de áudio.

As instruções do sistema são adicionadas ao comando antes do início da interação e permanecem em vigor durante toda a sessão.

As instruções do sistema só podem ser definidas no início de uma sessão, imediatamente após a conexão inicial. Para fornecer mais informações ao modelo durante a sessão, use atualizações incrementais de conteúdo.

Interrupções

Os usuários podem interromper a saída do modelo a qualquer momento. Quando a detecção de atividade de voz (VAD) detecta uma interrupção, a geração em andamento é cancelada e descartada. Apenas as informações já enviadas ao cliente são mantidas no histórico da sessão. Em seguida, o servidor envia uma mensagem BidiGenerateContentServerContent para informar a interrupção.

Além disso, o servidor do Gemini descarta todas as chamadas de função pendentes e envia uma mensagem BidiGenerateContentServerContent com os IDs das chamadas canceladas.

Vozes

Para especificar uma voz, defina o voiceName no objeto speechConfig como parte da configuração da sessão.

Confira a representação JSON a seguir de um objeto speechConfig:

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

Para conferir a lista de vozes disponíveis, consulte Mudar as configurações de voz e idioma.

Limitações

Considere as seguintes limitações da API Live e do Gemini 2.0 ao planejar seu projeto.

Autenticação do cliente

A API Live só oferece autenticação de servidor para servidor e não é recomendada para uso direto pelo cliente. A entrada do cliente precisa ser encaminhada por um servidor de aplicativos intermediário para autenticação segura com a API Live.

Duração máxima da sessão

A duração máxima padrão de uma sessão de conversa é de 10 minutos. Para mais informações, consulte Duração da sessão.

Detecção de atividade de voz (VAD)

Por padrão, o modelo realiza automaticamente a detecção de atividade de voz (VAD) em um stream de entrada de áudio contínuo. A VAD pode ser configurada com o campo RealtimeInputConfig.AutomaticActivityDetection da mensagem de configuração.

Quando o fluxo de áudio é pausado por mais de um segundo (por exemplo, quando o usuário desativa o microfone), um evento AudioStreamEnd é enviado para limpar o áudio em cache. O cliente pode retomar o envio de dados de áudio a qualquer momento.

Como alternativa, a VAD automática pode ser desativada definindo RealtimeInputConfig.AutomaticActivityDetection.disabled como true na mensagem de configuração. Nessa configuração, o cliente é responsável por detectar a fala do usuário e enviar mensagens ActivityStart e ActivityEnd nos momentos adequados. Um AudioStreamEnd não é enviado nessa configuração. Em vez disso, qualquer interrupção do stream é marcada por uma mensagem ActivityEnd.

Outras limitações

Não há suporte para a inclusão manual de endpoints.

Entradas e saídas de áudio afetam negativamente a capacidade do modelo de usar a chamada de função.

Contagem de tokens

Não há suporte para a contagem de tokens.

Limites de taxas

Os seguintes limites de taxa são aplicáveis:

• 5.000 sessões simultâneas por chave de API
• 4 milhões de tokens por minuto

Mensagens e eventos

A seguir

• Saiba mais sobre chamadas de funções.
• Consulte a referência de chamada de função para exemplos.