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, você pode oferecer aos usuários finais a experiência de conversas naturais e semelhantes às humanas, além de interromper as respostas do modelo usando comandos de voz. A API Live pode processar entradas de texto, áudio e vídeo e 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 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 ferramenta: é possível integrar o modelo a serviços e fontes de dados externos.

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

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

Modelos compatíveis

Primeiros passos

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

A API Live é uma API stateful que usa WebSockets.

Esta seção mostra um exemplo de como usar a API Live para geração de texto-texto usando o 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,
    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 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 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, instruções do sistema e 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 conjunto de objetos a seguir:

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

Mensagens de cliente com suporte

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

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 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 com suporte

Confira as 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 o contexto da sessão ou restaurar o contexto da sessão. Para contextos curtos, você pode enviar interações passo a passo para representar a sequência exata de eventos. Para contextos mais longos, é recomendável fornecer um único resumo de 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 do conteúdo possam ser do tipo functionResponse, BidiGenerateContentClientContent não pode ser usado para fornecer uma resposta às chamadas de função emitidas pelo modelo. Use BidiGenerateContentToolResponse. O BidiGenerateContentClientContent só deve ser usado para estabelecer o 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 da 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 dos recursos da função.

• parameters (objeto): define os dados de entrada necessários pela 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 do objetivo e do formato esperado do parâmetro.

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

Para conferir exemplos de código de uma declaração de função usando comandos curl, consulte Chamada de função com a API Gemini. Para conferir 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 posteriores. A execução é pausada até que os resultados de cada chamada de função fiquem disponíveis, o que garante o 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 ao 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 entradas ao modelo durante a sessão, use atualizações de conteúdo incrementais.

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. Somente as informações já enviadas ao cliente são retidas no histórico da sessão. Em seguida, o servidor envia uma mensagem BidiGenerateContentServerContent para informar a interrupção.

Além disso, o servidor 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 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 compatí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 do cliente. A entrada do cliente precisa ser roteada por um servidor de aplicativo 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, na sigla em inglês) em um stream de entrada de áudio contínuo. O VAD pode ser configurado 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 desliga o microfone), um evento AudioStreamEnd é enviado para limpar todo o áudio em cache. O cliente pode retomar o envio de dados de áudio a qualquer momento.

Como alternativa, o VAD automático pode ser desativado 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 apropriados. Um AudioStreamEnd não é enviado nesta configuração. Em vez disso, qualquer interrupção do fluxo é marcada por uma mensagem ActivityEnd.

Outras limitações

Não há suporte para endpoint manual.

As entradas e saídas de áudio afetam negativamente a capacidade do modelo de usar chamadas de função.

Contagem de tokens

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

Limites de taxas

Os seguintes limites de taxa se aplicam:

• Três 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ção.
• Consulte a Referência de chamada de função para conferir exemplos.