Live API

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. O modelo pode processar entradas de texto, áudio e vídeo e fornecer saídas de texto e áudio.

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

O que há de novo

A API Live tem novos recursos e capacidades.

Novos recursos:

• Duas novas vozes e 30 novos idiomas, com idioma de saída configurável
• Resoluções de imagem configuráveis 66/256 tokens
• Cobertura de giro configurável: envie todas as entradas o tempo todo ou apenas quando o usuário estiver falando.
• Configurar se a entrada deve interromper o modelo ou não
• Detecção de atividade de voz configurável e novos eventos do cliente para sinalização de fim de turno
• Contagem de tokens
• Um evento do cliente para sinalizar o fim do stream
• Streaming de texto
• Ressuscitar a sessão configurável, com dados de sessão armazenados no servidor por 24 horas
• Suporte a sessões mais longas com uma janela de contexto deslizante

Novos eventos de cliente:

• Fim do stream de áudio / microfone fechado
• Eventos de início/término da atividade para controlar manualmente a transição de volta

Novos eventos do servidor:

• Notificação de dispensa sinalizando a necessidade de reiniciar uma sessão
• Geração concluída

Usar a API Live

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

Enviar e receber mensagens de texto

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=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-live-001"

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_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

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

            # Un-comment this code 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 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:

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(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 único resumo de mensagem para liberar a janela de contexto para interações subsequentes.

Mudar vozes

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

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

Alterar idioma

A API Live oferece suporte a vários idiomas.

Para mudar o idioma, defina o código do idioma 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(
        language_code="de-DE",
    )
)

Usar chamadas de função

É possível definir ferramentas com a API 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_client_content(
        turns={
            "role": "user",
            "parts": [{"text": "Turn the lights down to a romantic level"}],
        },
        turn_complete=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 True:
        # The generation was interrupted

Configurar a 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 fluxo de entrada de áudio contínuo. O VAD pode ser configurado com o campo realtimeInputConfig.automaticActivityDetection da configuração de configuração.

Quando o stream de áudio é pausado por mais de um segundo (por exemplo, porque o usuário desativou o microfone), um evento audioStreamEnd precisa ser 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.

O suporte do SDK para esse recurso vai estar disponível nas próximas semanas.

Receber a contagem de tokens

Você pode encontrar o número total de tokens consumidos no campo usageMetadata da mensagem do servidor retornada.

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

Estender a duração da sessão

A duração máxima da sessão pode ser estendida para ilimitada com dois mecanismos:

• Ativar a compactação da janela de contexto
• Configurar a retomada da sessão

Além disso, você vai receber uma mensagem de saída antes do término da sessão, permitindo que você realize outras ações.

Ativar a compactação de janelas de contexto

Para permitir sessões mais longas e evitar o encerramento abrupto da conexão, ative a compressão da janela de contexto definindo o campo contextWindowCompression como parte da configuração da sessão.

Em ContextWindowCompressionConfig, é possível configurar um mecanismo de janela deslizante e o número de tokens que aciona a compactação.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

Configurar a retomada da sessão

Para evitar o encerramento da sessão quando o servidor redefinir periodicamente a conexão WebSocket, configure o campo sessionResumption na configuração de configuração.

A transmissão dessa configuração faz com que o servidor envie mensagens SessionResumptionUpdate, que podem ser usadas para retomar a sessão transmitindo o último token de retomada como SessionResumptionConfig.handle da conexão subsequente.

from google.genai import types

print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
    model="gemini-2.0-flash-live-001",
    config=types.LiveConnectConfig(
        response_modalities=["AUDIO"],
        session_resumption=types.SessionResumptionConfig(
            # The handle of the session to resume is passed here,
            # or else None to start a new session.
            handle=previous_session_handle
        ),
    ),
) as session:
    # Session connected
    while True:
        await session.send_client_content(
            turns=types.Content(
                role="user", parts=[types.Part(text="Hello world!")]
            )
        )
        async for message in session.receive():
            # Periodically, the server will send update messages that may
            # contain a handle for the current state of the session.
            if message.session_resumption_update:
                update = message.session_resumption_update
                if update.resumable and update.new_handle:
                    # The handle should be retained and linked to the session.
                    return update.new_handle

            # For the purposes of this example, placeholder input is continually fed
            # to the model. In non-sample code, the model inputs would come from
            # the user.
            if message.server_content and message.server_content.turn_complete:
                break

Receber uma mensagem antes da desconexão da sessão

O servidor envia uma mensagem GoAway que sinaliza que a conexão atual será encerrada em breve. Essa mensagem inclui o timeLeft, que indica o tempo restante e permite que você tome outras medidas antes que a conexão seja encerrada como ABORTED.

async for response in session.receive():
    if response.go_away is not None:
        # The connection will soon be terminated
        print(response.go_away.time_left)

Receber uma mensagem quando a geração for concluída

O servidor envia uma mensagem generationComplete que indica que o modelo terminou de gerar a resposta.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

Mudar a resolução da mídia

É possível especificar a resolução da mídia de entrada definindo o campo mediaResolution como parte da configuração da sessão:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

Limitações

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

Modalidades de resposta

Só é possível definir uma modalidade de resposta (TEXT ou AUDIO) por sessão na configuração da sessão. Tentar definir os dois resultará em uma mensagem de erro de configuração. Isso significa que você pode configurar o modelo para responder com texto ou áudio, mas não com os dois na mesma sessão.

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 da sessão

A duração da sessão pode ser estendida para um número ilimitado ativando a compressão. Sem compressão, as sessões somente de áudio são limitadas a 15 minutos, e as sessões de áudio e vídeo são limitadas a 2 minutos. Exceder esses limites sem compressão encerrará a conexão.

Além disso, você pode configurar a retomada de sessão para permitir que o cliente retome uma sessão encerrada.

Janela de contexto

Uma sessão tem um limite de janela de contexto de 32 mil tokens.

Idiomas aceitos

A API Live é compatível com os seguintes idiomas:

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)