Ir al contenido principal
Español— Elegir un idioma
Menú

Sesiones, eventos y ciclo de vida

Lección 2 de 18 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Sesiones, eventos y ciclo de vida
  2. El ciclo de vida de una sesión
  3. Configuración de una sesión
  4. El sistema de eventos
  5. Gestión de errores
  6. Puntos clave

Actualizado el 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos: tts-1, tts-1-hd y gpt-4o-mini-tts dejará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-realtime y 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-transcribe y /v1/audio/translations el 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 ni server_vad ni semantic_vad. En una sesión de conversación como esta, donde el VAD valida cada turno, la documentación especifica gpt-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:

1

Conexión → session.created

El servidor confirma la sesión con un ID único y una configuración predeterminada.

2

Configuración → session.update

Envías session.update para definir instrucciones, voz, herramientas y modalidades.

3

Conversación activa

Intercambio de eventos de audio y texto entre cliente y servidor.

4

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.update configura la sesión tras session.created; espera a session.updated antes de confiar en la nueva configuración
  • Para transcribir la entrada en una sesión de conversación, usa gpt-transcribe; gpt-live-transcribe está reservado para sesiones de transcripción
  • El protocolo es puramente dirigido por eventos: cada mensaje tiene un type que 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