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 por voz 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 direção
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 permanecer 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"
}
}
}
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 not None:
# 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 stream 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.
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.
from google.genai import types
async with client.aio.live.connect(
model='gemini-2.0-flash-live-001',
config=types.LiveConnectConfig(
response_modalities=['AUDIO'],
),
) 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():
# 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}')
# 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
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.
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.
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(),
)
),
)
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.
Autenticação do cliente
A API Live fornece apenas 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.
Janela de contexto
Uma sessão tem um limite de janela de contexto de 32 mil tokens.
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)