Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Sessões, eventos e ciclo de vida

Aula 2 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Sessões, eventos e ciclo de vida
  2. O ciclo de vida de uma sessão
  3. Configurar uma sessão
  4. O sistema de eventos
  5. Tratamento de erros
  6. Pontos-chave

Atualizado a 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos: tts-1, tts-1-hd e gpt-4o-mini-tts deixarã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-realtime e 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-transcribe e /v1/audio/translations a 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 nem server_vad nem semantic_vad. Numa sessão de conversação como esta, onde o VAD valida cada turno, a documentação especifica gpt-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:

1

Ligação → session.created

O servidor confirma a sessão com um ID único e uma configuração padrão.

2

Configuração → session.update

Envia session.update para definir instruções, voz, ferramentas e modalidades.

3

Conversação ativa

Troca de eventos de áudio e texto entre o cliente e o servidor.

4

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.update configura a sessão após session.created; aguarde por session.updated antes de confiar na nova configuração
  • Para transcrever a entrada numa sessão de conversação, utilize gpt-transcribe; gpt-live-transcribe está reservado para sessões de transcrição
  • O protocolo é puramente orientado por eventos: cada mensagem tem um type que 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