Multimodal Live API

A API Multimodal Live permite interações de voz e vídeo bidirecionais de baixa latência com o Gemini. Usando a API Multimodal Live, você pode oferecer aos usuários finais a experiência de conversas por voz naturais e semelhantes a humanos, 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.

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

Usar a API Multimodal Live

Esta seção descreve como usar a API Multimodal Live com um dos nossos SDKs. Para mais informações sobre a API WebSockets, consulte a referência da API WebSockets abaixo.

Enviar e receber mensagens de texto

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["TEXT"]}

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

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

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

Receber áudio

O exemplo a seguir mostra como receber dados de áudio e gravá-los em um arquivo .wav.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send(input=message, end_of_turn=True)

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Comment this out to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

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

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

Transmitir áudio e vídeo

Instruções do sistema

As instruções do sistema permitem orientar o comportamento de um modelo com base nas suas necessidades e casos de uso específicos. As instruções do sistema podem ser definidas na configuração de configuração e permanecem em vigor durante toda a sessão.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

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:

from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))

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

Para contextos mais longos, é recomendável fornecer um resumo de mensagem único para liberar a janela de contexto para interações subsequentes.

Mudar as vozes

A API Multimodal Live é compatível com as seguintes vozes: Aoede, Charon, Fenrir, Kore e Puck.

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

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Usar chamadas de função

É possível definir ferramentas com a API Multimodal Live. Consulte o tutorial de chamada de função para saber mais.

As ferramentas precisam ser definidas como parte da configuração da sessão:

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send(input="Turn the lights down to a romantic level", end_of_turn=True)

    async for response in session.receive():
        print(response.tool_call)

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 estejam disponíveis, o que garante o processamento sequencial.

O cliente precisa responder com BidiGenerateContentToolResponse.

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

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

async for response in session.receive():
    if response.server_content.interrupted is not None:
        # The generation was interrupted

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

Referência da API WebSockets

A API Multimodal Live é uma API stateful que usa WebSockets. Nesta seção, você vai encontrar mais detalhes sobre a API WebSockets.

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 mensagem inicial após a conexão define a configuração da sessão, que 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. O uso de maiúsculas e minúsculas nos SDKs pode variar. Consulte as opções de configuração do SDK do Python aqui.

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

Enviar mensagens

Para trocar mensagens pela conexão WebSocket, 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 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 estes guias:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

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:

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.

Integrações de terceiros

Para implantações de apps da Web e para dispositivos móveis, confira as opções em:

• Diariamente
• Livekit (em inglês)