Multimodal Live API

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

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:oferece 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, recuperando informações ouvidas ou vistas anteriormente.
• Suporte para chamada de função, execução de código e pesquisa como ferramenta:permite a integração com serviços e fontes de dados externos.
• Detecção automatizada de atividade de voz (VAD, na sigla em inglês): o modelo pode reconhecer com precisão quando o usuário começa e para de falar. Isso permite interações conversacionais naturais e permite que os usuários interrompam o modelo a qualquer momento.

Você pode testar a API Multimodal Live no Google AI Studio.

Primeiros passos

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.

Instalar a biblioteca da API Gemini

Para instalar o pacote google-genai, use o seguinte comando pip:

!pip3 install google-genai

Importar dependências

Para importar dependências:

from google import genai

Enviar e receber uma mensagem de texto

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

            async for response in session.receive():
                if response.text is None:
                    continue
                print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

Guia de integração

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

Sessões

Uma sessão representa uma única conexão WebSocket 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.
• Receba respostas 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, instruções do sistema e ferramentas.

Confira o exemplo de configuração a seguir:

{​​
  "model": string,
  "generation_config": {​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

Para mais informações, consulte BidiGenerateContentSetup.

Enviar mensagens

As mensagens são strings formatadas em JSON trocadas pela conexão WebSocket.

Para enviar uma mensagem, o cliente precisa enviar uma mensagem de cliente com suporte em uma string formatada em JSON com uma das conexões WebSocket abertas.

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 de mensagens do servidor com suporte.

Confira estes guias:

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

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

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": 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

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.

Consulte o tutorial de chamada de função para saber mais.

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.

As entradas e saídas de áudio afetam negativamente a capacidade do modelo de usar a 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

Você pode 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.

Negras

A API Multimodal Live oferece suporte aos seguintes vozes: Aoede, Charon, Fenrir, Kore e Puck.

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

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

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

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.

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

Histórico da conversa

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 até 15 minutos de á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.

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

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 e Tool, consulte Como gerar conteúdo.