Referência da API em tempo real

Este documento fornece uma referência para a API Live e mostra como usá-la para streaming bidirecional com o Gemini. Ele abrange os seguintes tópicos:

• Recursos:saiba mais sobre os principais recursos da API Live, incluindo multimodalidade e interação de baixa latência.
• Começar:encontre um exemplo de início rápido para usar a API com a geração de texto para texto.
• Guia de integração:entenda os conceitos básicos para integração com a API, como sessões, tipos de mensagens e chamadas de função.
• Limitações:revise as limitações atuais da API, incluindo duração da sessão e autenticação.
• Mensagens e eventos:consulte a referência detalhada de todas as mensagens do cliente e do servidor.

O diagrama a seguir resume o fluxo de trabalho geral:

A API Live permite conversas bidirecionais de voz e vídeo de baixa latência com o Gemini. É possível criar interações naturais e semelhantes às humanas para seus usuários, incluindo a capacidade de interromper as respostas do modelo com comandos de voz. A API Live processa entradas de texto, áudio e vídeo e fornece 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 e de baixa latência: receba respostas rápidas do modelo para uma experiência de conversa fluida.
• Memória de 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 chamada 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 projetada para comunicação de servidor para servidor. Para apps da Web e para dispositivos móveis, recomendamos que você use a integração dos nossos parceiros da 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 com Python 3.9 ou mais recente.

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, HttpOptions, LiveConnectConfig,
                                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

Nesta seção, descrevemos como integrar seu aplicativo à API Live.

Sessões

Uma conexão WebSocket estabelece uma sessão entre o cliente e o servidor do Gemini. Depois de iniciar uma nova conexão, o cliente pode trocar mensagens com o servidor para fazer o seguinte:

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

Envie a configuração da sessão na primeira mensagem depois de estabelecer uma 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.

Veja a seguir um exemplo de configuração:

{
  "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 envia 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

A tabela a seguir descreve as mensagens que você pode enviar ao servidor.

Receber mensagens

Para receber mensagens do Gemini, detecte o evento message do WebSocket. Em seguida, analise o resultado de acordo com as definições das mensagens do servidor compatíveis.

Exemplo:

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 têm 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

A tabela a seguir descreve as mensagens que você pode receber do servidor.

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, é possível enviar interações de turno a turno para representar a sequência exata de eventos. Para contextos mais longos, recomendamos que você forneça um único resumo da mensagem para liberar a janela de contexto para interações de acompanhamento.

Confira abaixo um exemplo de mensagem de contexto:

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

Embora as partes de conteúdo possam ser do tipo functionResponse, não use BidiGenerateContentClientContent para responder a chamadas de função do modelo. Em vez disso, use BidiGenerateContentToolResponse. Use BidiGenerateContentClientContent apenas 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

É necessário declarar todas as funções 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 da finalidade 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 ou 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 a operação 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 para encadear as saídas. Esse código é executado em um ambiente de sandbox e gera mensagens BidiGenerateContentToolCall subsequentes. A execução é pausada até que os resultados de cada chamada de função estejam disponíveis, o que fornece um processamento sequencial.

O cliente precisa 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. Só é possível definir esses parâmetros 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 que já foram 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.

Veja a seguir uma representação JSON 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 oferece apenas autenticação de servidor para servidor e não é recomendada para uso direto pelo cliente. Encaminhe a entrada do cliente 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. É possível configurar a VAD com o campo RealtimeInputConfig.AutomaticActivityDetection da mensagem de configuração.

A API é compatível com dois modos de VAD:

• VAD automático (padrão): o servidor detecta a fala do usuário.

  • Se o stream de áudio for pausado por mais de um segundo (por exemplo, quando o usuário silencia o microfone), um evento AudioStreamEnd será enviado para limpar o áudio em cache.
  • O cliente pode retomar o envio de dados de áudio a qualquer momento.

• VAD manual: para usar esse modo, defina RealtimeInputConfig.AutomaticActivityDetection.disabled como true na mensagem de configuração.

  • O cliente é responsável por detectar a fala do usuário e enviar mensagens ActivityStart e ActivityEnd nos momentos adequados.
  • Um evento AudioStreamEnd não é enviado nessa configuração. Em vez disso, uma mensagem ActivityEnd marca qualquer interrupção do stream.

Outras limitações

• Não há suporte para a inclusão manual de endpoints.
• Entradas e saídas de áudio podem afetar 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.