Sessões, eventos e ciclo de vida
Nesta página
Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos:
tts-1,tts-1-hdegpt-4o-mini-ttsdeixarão de funcionar a 6 de janeiro de 2027 (substituição:gpt-realtime-2.1-mini, que o guia TTS da OpenAI indica não ser suportado por/v1/audio/speech: a migração da síntese de fala passa para a Realtime API);gpt-realtime,gpt-4o-realtimee modelos de áudio legados a 20 de janeiro de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsa 26 de fevereiro de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz em full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026.
Corrigido a 3 de novembro de 2026. A transcrição de entrada utilizava
gpt-live-transcribe, que só funciona numa sessão de transcrição e não suporta nemserver_vadnemsemantic_vad. Numa sessão de conversação como esta, onde o VAD valida cada turno, a documentação especificagpt-transcribe, que transcreve turnos validados e utiliza turnos anteriores como contexto. Fontes: Transcrição em tempo real · GPT-Transcribe · GPT-Live-Transcribe.
Sessões, eventos e ciclo de vida
Cada ligação WebSocket à Realtime API cria uma sessão. Esta sessão é a unidade fundamental de gestão: encapsula a configuração do modelo, o histórico da conversação, as ferramentas disponíveis e o estado atual da interação. Compreender o seu ciclo de vida é essencial para construir agentes de voz robustos.
O ciclo de vida de uma sessão
Assim que a ligação WebSocket é estabelecida, o servidor emite um evento session.created. A sessão passa por várias fases:
Ligação → session.created
O servidor confirma a sessão com um ID único e uma configuração padrão.
Configuração → session.update
Envia session.update para definir instruções, voz, ferramentas e modalidades.
Conversação ativa
Troca de eventos de áudio e texto entre o cliente e o servidor.
Encerramento → WebSocket disconnect
A sessão é destruída quando a ligação fecha. Nenhum estado é retido no servidor.
Configurar uma sessão
Após session.created, envie um evento session.update para configurar o comportamento do modelo. Transcrever o que o utilizador diz (audio.input.transcription) é opcional: sem isso, recebe a voz mas não o texto. languages especifica os idiomas esperados e melhora o reconhecimento:
import asyncio
import websockets
import json
async def configure_session():
headers = {
"Authorization": f"Bearer {OPENAI_API_KEY}"
}
async with websockets.connect(URL, additional_headers=headers) as ws:
# Aguardar session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Session created: {session_id}")
# Configurar a sessão
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "You are a French-speaking voice assistant. "
"Respond concisely and naturally.",
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000},
"transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"prefix_padding_ms": 300,
"silence_duration_ms": 500
}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000},
"voice": "marin"
}
},
"tools": []
}
}))
# Aguardar confirmação (outros eventos podem chegar primeiro)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Session updated")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Principais parâmetros da sessão
| Parâmetro | Descrição | Valor recomendado |
|---|---|---|
| output_modalities | Modalidades de saída | ["audio"] (ou ["text"]) |
| audio.output.voice | Voz de síntese | marin, cedar, alloy, echo, etc. |
| audio.input.turn_detection | Deteção de fim de fala | server_vad com threshold 0.5 |
| audio.input.format | Formato de áudio de entrada | {"type": "audio/pcm", "rate": 24000} |
O sistema de eventos
A Realtime API é inteiramente orientada por eventos. Cada mensagem trocada é um objeto JSON com um campo type que determina a sua natureza. Os eventos dividem-se em duas categorias:
Eventos do cliente (você → servidor)
# Os principais eventos que envia
client_events = {
"session.update": "Modificar configuração",
"input_audio_buffer.append": "Enviar um bloco de áudio",
"input_audio_buffer.commit": "Confirmar o buffer de áudio",
"input_audio_buffer.clear": "Limpar o buffer de áudio",
"conversation.item.create": "Adicionar uma mensagem manualmente",
"conversation.item.truncate": "Truncar uma resposta",
"conversation.item.delete": "Eliminar uma mensagem",
"response.create": "Acionar uma resposta",
"response.cancel": "Cancelar a resposta atual",
}
Eventos do servidor (servidor → você)
# Os principais eventos que recebe
server_events = {
"session.created": "Sessão inicializada",
"session.updated": "Configuração aplicada",
"input_audio_buffer.speech_started": "Fala detetada",
"input_audio_buffer.speech_stopped": "Silêncio detetado",
"conversation.item.created": "Nova mensagem no histórico",
"response.created": "Geração iniciada",
"response.output_audio.delta": "Bloco de áudio da resposta",
"response.output_audio_transcript.delta": "Bloco de transcrição",
"response.done": "Resposta concluída",
"error": "Erro",
}
Tratamento de erros
Os erros são emitidos através de um evento do tipo error. Deve sempre intercetá-los:
async def handle_events(ws):
async for raw_message in ws:
event = json.loads(raw_message)
event_type = event["type"]
if event_type == "error":
error = event["error"]
print(f"Error [{error['type']}]: {error['message']}")
if error["type"] == "invalid_request_error":
# Erro de configuração, corrigir e tentar novamente
pass
elif error["type"] == "server_error":
# Problema do lado da OpenAI, reconectar
pass
elif event_type == "session.updated":
print("Configuration applied successfully")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Tokens used: {usage}")
Pontos-chave
- Uma sessão é criada automaticamente aquando da ligação WebSocket e destruída aquando da desconexão
session.updateconfigura a sessão apóssession.created; aguarde porsession.updatedantes de confiar na nova configuração- Para transcrever a entrada numa sessão de conversação, utilize
gpt-transcribe;gpt-live-transcribeestá reservado para sessões de transcrição - O protocolo é puramente orientado por eventos: cada mensagem tem um
typeque determina o seu tratamento - Os eventos do cliente conduzem a interação; os eventos do servidor reportam os resultados
- O tratamento de erros é crítico: escute sempre os eventos
error