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

Confira o Changelog para conferir os novos recursos e recursos da API Live.

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.

Para usar todos os recursos, instale a versão mais recente do SDK, por exemplo, pip install -U google-genai.

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

Os dados de áudio na API Live são sempre brutos, little-endian e PCM de 16 bits. A saída de áudio sempre usa uma taxa de amostragem de 24 kHz. O áudio de entrada é nativo de 16 kHz, mas a API Live vai fazer uma nova amostragem, se necessário, para que qualquer taxa de amostragem possa ser enviada. Para transmitir a taxa de amostragem do áudio de entrada, defina o tipo MIME de cada Blob que contém áudio para um valor como audio/pcm;rate=16000.

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:

Python

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)

JSON

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

Python

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

JSON

{
  "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 ferramentas

É possível definir ferramentas como Chamada de função, Execução de código e Pesquisa Google com a API Live.

Usar chamadas de função

É possível definir declarações de função como parte da configuração da sessão. Consulte o tutorial de chamada de função para saber mais.

Depois de receber chamadas de ferramentas, o cliente precisa responder com uma lista de objetos FunctionResponse usando o método session.send_tool_response.

import asyncio
from google import genai
from google.genai import types

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

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


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

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.

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

Usar a execução de código

É possível definir a execução do código como parte da configuração da sessão. Consulte o tutorial de execução de código para saber mais.

import asyncio
from google import genai
from google.genai import types

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

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

É possível ativar o embasamento com a Pesquisa Google como parte da configuração da sessão. Consulte o tutorial de embasamento para saber mais.

import asyncio
from google import genai
from google.genai import types

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

tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

Combinar várias ferramentas

É possível combinar várias ferramentas na API Live:

prompt = """
Hey, I need you to do three things for me.

1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"code_execution": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

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

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

Você pode configurar ou desativar a detecção de atividade de voz (VAD).

Usar o VAD automático

Por padrão, o modelo realiza a VAD automaticamente 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 fluxo 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.

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
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:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

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

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

Com send_realtime_input, a API vai responder ao áudio automaticamente com base no VAD. Enquanto send_client_content adiciona mensagens ao contexto do modelo em ordem, send_realtime_input é otimizado para resposta à custa de ordenação determinística.

Configurar o VAD automático

Para ter mais controle sobre a atividade de VAD, configure os seguintes parâmetros. Consulte a referência da API para mais informações.

from google.genai import types

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

Desativar o VAD automático

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.

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

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:

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.

import asyncio
from google import genai
from google.genai import types

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

async def main():
    print(f"Connecting to the service with handle {previous_session_handle}...")
    async with client.aio.live.connect(
        model=model,
        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:
        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

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

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

Receber transcrições de áudio

É possível ativar a transcrição da saída de áudio do modelo. O idioma da transcrição é inferido da resposta do modelo.

import asyncio
from google import genai
from google.genai import types

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

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)


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

É possível ativar a transcrição da entrada de áudio enviando input_audio_transcription na configuração de configuração.

import asyncio
from google import genai
from google.genai import types

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

config = {"response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {"disabled": True},
        "activity_handling": "NO_INTERRUPTION",
    },
    "input_audio_transcription": {},
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_data = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(activity_start=types.ActivityStart())
        await session.send_realtime_input(
            audio=types.Blob(data=audio_data, mime_type='audio/pcm;rate=16000')
        )
        await session.send_realtime_input(activity_end=types.ActivityEnd())

        async for msg in session.receive():
            if msg.server_content.input_transcription:
                print('Transcript:', msg.server_content.input_transcription.text)

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

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 de 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, é possível 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:

Idioma Código BCP-47
Alemão (Alemanha) de-DE
Inglês (Austrália) en-AU
Inglês (Reino Unido) en-GB
Inglês (Índia) en-IN
Inglês (EUA) en-US
Espanhol (Estados Unidos) es-US
Francês (França) fr-FR
Híndi (Índia) hi-IN
Português (Brasil) pt-BR
Árabe (genérico) ar-XA
Espanhol (Espanha) es-ES
Francês (Canadá) fr-CA
Indonésio (Indonésia) id-ID
Italiano (Itália) it-IT
Japonês (Japão) ja-JP
Turco (Turquia) tr-TR
Vietnamita (Vietnã) vi-VN
Bengali (Índia) bn-IN
Gujarati (Índia) gu-IN
Canarês (Índia) kn-IN
Malaiala (Índia) ml-IN
Marati (Índia) mr-IN
Tâmil (Índia) ta-IN
Telugo (Índia) te-IN
Holandês (Holanda) nl-NL
Coreano (Coreia do Sul) ko-KR
Chinês mandarim (China) cmn-CN
Polonês (Polônia) pl-PL
Russo (Rússia) ru-RU
Tailandês (Tailândia) th-TH

Integrações de terceiros

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