Sesiones, eventos y ciclo de vida
En esta página
Actualizado el 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos:
tts-1,tts-1-hdygpt-4o-mini-ttsdejarán de funcionar el 6 de enero de 2027 (sustituto:gpt-realtime-2.1-mini, que la guía de TTS de OpenAI indica que no es compatible con/v1/audio/speech: la migración de la síntesis de voz se traslada a la Realtime API);gpt-realtime,gpt-4o-realtimey los modelos de audio heredados el 20 de enero de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribey/v1/audio/translationsel 26 de febrero de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para la voz a dúplex completo, GPT-Live 1 está disponible en la API desde el 10 de septiembre de 2026.
Corregido el 3 de noviembre de 2026. La transcripción de entrada utilizaba
gpt-live-transcribe, que solo funciona en una sesión de transcripción y no admite niserver_vadnisemantic_vad. En una sesión de conversación como esta, donde el VAD valida cada turno, la documentación especificagpt-transcribe, que transcribe los turnos validados y utiliza los turnos anteriores como contexto. Fuentes: Transcripción en tiempo real · GPT-Transcribe · GPT-Live-Transcribe.
Sesiones, eventos y ciclo de vida
Cada conexión WebSocket a la Realtime API crea una sesión. Esta sesión es la unidad fundamental de gestión: encapsula la configuración del modelo, el historial de la conversación, las herramientas disponibles y el estado actual de la interacción. Comprender su ciclo de vida es esencial para construir agentes de voz robustos.
El ciclo de vida de una sesión
Tan pronto como se establece la conexión WebSocket, el servidor emite un evento session.created. La sesión pasa por varias fases:
Conexión → session.created
El servidor confirma la sesión con un ID único y una configuración predeterminada.
Configuración → session.update
Envías session.update para definir instrucciones, voz, herramientas y modalidades.
Conversación activa
Intercambio de eventos de audio y texto entre cliente y servidor.
Cierre → WebSocket disconnect
La sesión se destruye cuando se cierra la conexión. El servidor no conserva ningún estado.
Configuración de una sesión
Tras recibir session.created, envía un evento session.update para configurar el comportamiento del modelo. La transcripción de lo que dice el usuario (audio.input.transcription) es opcional: sin ella, recibes la voz pero no el texto. languages especifica los idiomas esperados y mejora el reconocimiento:
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:
# Esperar a session.created
event = json.loads(await ws.recv())
session_id = event["session"]["id"]
print(f"Sesión creada: {session_id}")
# Configurar la sesión
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "Eres un asistente de voz francófono. "
"Responde de forma concisa y natural.",
"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": []
}
}))
# Esperar confirmación (pueden llegar otros eventos antes)
while True:
event = json.loads(await ws.recv())
if event["type"] == "session.updated":
print("Sesión actualizada")
break
if event["type"] == "error":
raise RuntimeError(event["error"]["message"])
Parámetros clave de la sesión
| Parámetro | Descripción | Valor recomendado |
|---|---|---|
| output_modalities | Modalidades de salida | ["audio"] (o ["text"]) |
| audio.output.voice | Voz de síntesis | marin, cedar, alloy, echo, etc. |
| audio.input.turn_detection | Detección de fin de habla | server_vad con umbral 0,5 |
| audio.input.format | Formato de audio entrante | {"type": "audio/pcm", "rate": 24000} |
El sistema de eventos
La Realtime API es completamente dirigida por eventos. Cada mensaje intercambiado es un objeto JSON con un campo type que determina su naturaleza. Los eventos se dividen en dos categorías:
Eventos de cliente (tú → servidor)
# Los principales eventos que envías
client_events = {
"session.update": "Modificar configuración",
"input_audio_buffer.append": "Enviar un fragmento de audio",
"input_audio_buffer.commit": "Confirmar el búfer de audio",
"input_audio_buffer.clear": "Limpiar el búfer de audio",
"conversation.item.create": "Añadir un mensaje manualmente",
"conversation.item.truncate": "Truncar una respuesta",
"conversation.item.delete": "Eliminar un mensaje",
"response.create": "Activar una respuesta",
"response.cancel": "Cancelar la respuesta actual",
}
Eventos de servidor (servidor → tú)
# Los principales eventos que recibes
server_events = {
"session.created": "Sesión inicializada",
"session.updated": "Configuración aplicada",
"input_audio_buffer.speech_started": "Habla detectada",
"input_audio_buffer.speech_stopped": "Silencio detectado",
"conversation.item.created": "Nuevo mensaje en el historial",
"response.created": "Generación iniciada",
"response.output_audio.delta": "Fragmento de audio de respuesta",
"response.output_audio_transcript.delta": "Fragmento de transcripción",
"response.done": "Respuesta finalizada",
"error": "Error",
}
Gestión de errores
Los errores se emiten mediante un evento de tipo error. Debes interceptarlos siempre:
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":
# Error de configuración, corregir y reintentar
pass
elif error["type"] == "server_error":
# Problema en el lado de OpenAI, reconectar
pass
elif event_type == "session.updated":
print("Configuración aplicada correctamente")
elif event_type == "response.done":
usage = event["response"].get("usage", {})
print(f"Tokens utilizados: {usage}")
Puntos clave
- Una sesión se crea automáticamente al establecer la conexión WebSocket y se destruye al desconectar
session.updateconfigura la sesión trassession.created; espera asession.updatedantes de confiar en la nueva configuración- Para transcribir la entrada en una sesión de conversación, usa
gpt-transcribe;gpt-live-transcribeestá reservado para sesiones de transcripción - El protocolo es puramente dirigido por eventos: cada mensaje tiene un
typeque determina su tratamiento - Los eventos de cliente impulsan la interacción; los eventos de servidor informan de los resultados
- La gestión de errores es crítica: escucha siempre los eventos
error