API Multimodal Live

A API Multimodal Live permite interações bidirecionais de baixa latência que usam entrada de texto, áudio e vídeo, com saída de áudio e texto. Isso facilita conversas por voz naturais e semelhantes a humanos com a capacidade de interromper o modelo a qualquer momento. O recurso de compreensão de vídeo do modelo amplia as modalidades de comunicação, permitindo que você compartilhe a entrada da câmera ou screencasts e faça perguntas sobre eles.

Recursos

A API Multimodal 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 a 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 Multimodal Live foi projetada 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.

Primeiros passos

Para testar a API Multimodal Live, acesse o Vertex AI Studio e clique em Testar Multimodal Live.

A API Multimodal Live é uma API stateful que usa WebSockets.

Esta seção mostra um exemplo de como usar a API Multimodal Live para geração de texto para texto usando Python 3.9 ou mais recente.

SDK da Gen AI para Python

Saiba como instalar ou atualizar o SDK do Google Gen AI para Python.
Para mais informações, consulte a documentação de referência da API SDK do Gen AI para Python ou o python-genai repositório do GitHub.
Defina as variáveis de ambiente para usar o SDK da IA generativa com a Vertex AI: 

# 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=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import LiveConnectConfig, HttpOptions, Modality

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-exp"

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(input=text_input, end_of_turn=True)

    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 Multimodal 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 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, 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:

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 ou vídeo 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 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
}

Mensagens do servidor com suporte

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

Mensagem Descrição
BidiGenerateContentSetupComplete Uma mensagem BidiGenerateContentSetup do cliente, enviada quando a configuração é concluída
BidiGenerateContentServerContent Conteúdo gerado pelo modelo em resposta a uma mensagem do cliente
BidiGenerateContentToolCall Solicitação para que o cliente execute as chamadas de função e retorne as respostas com os IDs correspondentes
BidiGenerateContentToolCallCancellation É enviado quando uma chamada de função é cancelada devido à interrupção da saída do modelo pelo usuário.

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 do 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 Introdução à 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 deve responder com BidiGenerateContentToolResponse.

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

Formatos de áudio

A API Multimodal Live é compatível com os seguintes formatos de áudio:

  • Formato de áudio de entrada: áudio PCM bruto de 16 bits a 16 kHz little-endian
  • Formato de áudio de saída: áudio PCM bruto de 16 bits a 24 kHz little-endian

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

A API Multimodal Live é compatível com as seguintes vozes:

  • Disco
  • Caronte
  • Kore
  • Fenrir
  • Aoede

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

Limitações

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

Autenticação do cliente

A API Multimodal 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 Multimodal Live.

Histórico de conversas

Embora o modelo acompanhe as interações na sessão, o histórico de conversas não é armazenado. Quando uma sessão termina, o contexto correspondente é apagado.

Para restaurar uma sessão anterior ou fornecer ao modelo o contexto histórico das interações do usuário, o aplicativo precisa manter o próprio registro de conversas e usar uma mensagem BidiGenerateContentClientContent para enviar essas informações no início de uma nova sessão.

Duração máxima da sessão

A duração da sessão é limitada a 15 minutos para áudio ou até 2 minutos de áudio e vídeo. Quando a duração da sessão excede o limite, a conexão é encerrada.

O modelo também é limitado pelo tamanho do contexto. O envio de grandes quantidades de conteúdo com os streams de vídeo e áudio pode resultar no encerramento precoce da sessão.

Detecção de atividade de voz (VAD)

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 está sempre ativado, e os parâmetros não podem ser configurados.

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 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 se aplicam:

  • Três sessões simultâneas por chave de API
  • 4 milhões de tokens por minuto

Mensagens e eventos

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

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 vai aguardar outras mensagens antes de iniciar a geração.

BidiGenerateContentRealtimeInput

Entrada do usuário enviada em tempo real.

Isso é diferente de ClientContentUpdate de algumas maneiras:

  • Podem ser enviados continuamente sem interrupção para a geração de modelos.
  • Se for necessário misturar dados intercalados entre ClientContentUpdate e RealtimeUpdate, o servidor vai tentar otimizar para 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.
  • Sempre é considerada a entrada do usuário (não pode ser usada para preencher o histórico de conversas).
Campos
media_chunks[]

Blob

Opcional. Dados de bytes inline para entrada de mídia.

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 o buffer e reproduzir em tempo real.

Campos
turn_complete

bool

Apenas saída. Se verdadeiro, indica que a geração do modelo foi concluída. A geração só vai começar em resposta a outras mensagens do cliente. Pode ser definido com content, indicando que content é o último na vez.
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 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.
grounding_metadata

GroundingMetadata

Apenas saída. Os metadados especificam as origens usadas para fundamentar o conteúdo gerado.
model_turn

Content

Apenas saída. O conteúdo que o modelo gerou como parte da conversa atual com o usuário.

BidiGenerateContentSetup

Mensagem a ser enviada na primeira e única mensagem do cliente. Contém a configuração que será aplicada durante a sessão de streaming.

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

Campos
model

string

Obrigatório. O nome totalmente qualificado do endpoint do modelo do editor ou do modelo ajustado a ser usado.

Formato do modelo do editor: projects/{project}/locations/{location}/publishers/\*/models/\*
generation_config

GenerationConfig

Opcional. Configuração de geração.

Os seguintes campos não são compatíveis:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_instruction

Content

Opcional. O usuário forneceu instruções do sistema para o modelo. Observação: use apenas texto em partes. O conteúdo de cada parte vai 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.

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
function_calls[]

FunctionCall

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

BidiGenerateContentToolCallCancellation

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

Campos
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
function_responses[]

FunctionResponse

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

A seguir