Referencia de la API Voice Live 2025-10-01

La API Voice Live proporciona comunicación bidireccional en tiempo real para aplicaciones habilitadas por voz que utilizan conexiones WebSocket. Esta API soporta funciones avanzadas como reconocimiento de voz, síntesis de texto a voz, transmisión de avatares, datos de animación y capacidades completas de procesamiento de audio.

La API utiliza eventos en formato JSON enviados por conexiones WebSocket para gestionar conversaciones, flujos de audio, interacciones con avatares y respuestas en tiempo real. Los eventos se categorizan en eventos del cliente (enviados de cliente a servidor) y eventos del servidor (enviados de servidor a cliente).

Key Features

• Procesamiento de audio en tiempo real: Soporte para múltiples formatos de audio, incluyendo PCM16 a distintas frecuencias de muestreo y códecs G.711
• Opciones avanzadas de voz: voces OpenAI, voces personalizadas Azure, voces estándar Azure y voces personales Azure
• Integración de Avatares: Streaming de avatares basado en WebRTC con vídeo, animación y blendshapes
• Detección Inteligente de Giro: Múltiples opciones de VAD, incluyendo Azure VAD semántica y detección en el lado del servidor
• Mejora de audio: reducción de ruido y cancelación de eco integradas
• Llamada de Función: Integración de herramientas para mejorar las capacidades conversacionales
• Gestión flexible de sesión: modalidades de salida, instrucciones y parámetros de respuesta configurables

Client Events

La API de Voice Live soporta los siguientes eventos del cliente que pueden enviarse desde el cliente al servidor:

session.update

Actualiza la configuración de la sesión. Este evento puede enviarse en cualquier momento para modificar configuraciones como voz, modalidades de salida, detección de giros, herramientas y otros parámetros de sesión. Ten en cuenta que una vez que una sesión se inicializa con un modelo concreto, no puede cambiarse a otro modelo.

Event Structure

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Properties

Ejemplo con Azure Custom Voice

{
  "type": "session.update",
  "session": {
    "voice": {
      "type": "azure-custom",
      "name": "my-custom-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "temperature": 0.7,
      "style": "cheerful"
    },
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "avatar": {
      "character": "lisa",
      "customized": false,
      "video": {
        "resolution": {
          "width": 1920,
          "height": 1080
        },
        "bitrate": 2000000
      }
    }
  }
}

session.avatar.connect

Establece una conexión avatar proporcionando la oferta SDP (Protocolo de Descripción de Sesión) del cliente para la negociación de medios WebRTC. Este evento es obligatorio cuando se usan características de avatar.

Event Structure

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

Properties

input_audio_buffer.append

Añadir bytes de audio al búfer de audio de entrada.

Event Structure

{
  "type": "input_audio_buffer.append",
  "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Properties

input_audio_buffer.commit

Compromete el búfer de audio de entrada para procesar.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Borra el búfer de audio de entrada.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

Añade un nuevo elemento al contexto de la conversación. Esto puede incluir mensajes, llamadas a funciones y respuestas a llamadas de función. Los elementos pueden insertarse en posiciones específicas del historial de conversación.

Event Structure

{
  "type": "conversation.item.create",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Properties

Ejemplo con contenido de audio

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello there"
      }
    ]
  }
}

Ejemplo con salida de llamada a función

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_123",
    "output": "{\"location\": \"San Francisco\", \"temperature\": \"70\"}"
  }
}

Ejemplo con la respuesta de aprobación del MCP

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_approval_response",
    "approval_request_id": "mcp_approval_req_456",
    "approve": true,
  }
}

conversation.item.retrieve

Recupera un elemento específico del historial de conversaciones. Esto es útil para inspeccionar el audio procesado tras la cancelación de ruido y el VAD.

Event Structure

{
  "type": "conversation.item.retrieve",
  "item_id": "item_ABC123"
}

Properties

conversation.item.truncate

Trunca el contenido de audio de un mensaje asistente. Esto es útil para detener la reproducción en un punto específico y sincronizar la comprensión del servidor con el estado del cliente.

Event Structure

{
  "type": "conversation.item.truncate",
  "item_id": "item_ABC123",
  "content_index": 0,
  "audio_end_ms": 5000
}

Properties

conversation.item.delete

Elimina un elemento del historial de conversaciones.

Event Structure

{
  "type": "conversation.item.delete",
  "item_id": "item_ABC123"
}

Properties

response.create

Instruye al servidor para que genere una respuesta mediante inferencia de modelo. Este evento puede especificar una configuración específica de respuesta que anule los valores predeterminados de la sesión.

Event Structure

{
  "type": "response.create",
  "response": {
    "modalities": ["text", "audio"],
    "instructions": "Be extra helpful and detailed.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "output_audio_format": "pcm16",
    "temperature": 0.7,
    "max_response_output_tokens": 1000
  }
}

Properties

Ejemplo con elección de herramienta

{
  "type": "response.create",
  "response": {
    "modalities": ["text"],
    "tools": [
      {
        "type": "function",
        "name": "get_current_time",
        "description": "Get the current time",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    ],
    "tool_choice": "get_current_time",
    "temperature": 0.3
  }
}

Ejemplo con animación

{
  "type": "response.create",
  "response": {
    "modalities": ["audio", "animation"],
    "animation": {
      "model_name": "default",
      "outputs": ["blendshapes", "viseme_id"]
    },
    "voice": {
      "type": "azure-custom",
      "name": "my-expressive-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012",
      "style": "excited"
    }
  }
}

response.cancel

Cancela una respuesta en curso. Esto detiene inmediatamente la generación de respuestas y la salida de audio relacionada.

Event Structure

{
  "type": "response.cancel"
}

Properties

input_audio_buffer.append

El evento cliente input_audio_buffer.append se utiliza para añadir bytes de audio al búfer de audio de entrada. El buffer de audio es un almacenamiento temporal donde puedes escribir y luego hacer un commit.

En el modo Server VAD (Detección de Actividad de Voz), el buffer de audio se utiliza para detectar el habla y el servidor decide cuándo hacer el comet. Cuando el VAD del servidor está desactivado, el cliente puede elegir cuánto audio colocar en cada evento hasta un máximo de 15 MiB. Por ejemplo, transmitir fragmentos más pequeños desde el cliente puede permitir que el VAD sea más responsivo.

A diferencia de la mayoría de los eventos del cliente, el servidor no envía una respuesta de confirmación al evento del cliente input_audio_buffer.append .

Event structure

{
  "type": "input_audio_buffer.append",
  "audio": "<audio>"
}

Properties

input_audio_buffer.clear

El evento cliente input_audio_buffer.clear se utiliza para borrar los bytes de audio en el búfer.

El servidor responde con un input_audio_buffer.cleared evento.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

El evento cliente input_audio_buffer.commit se utiliza para confirmar el búfer de audio de entrada del usuario, que crea un nuevo elemento de mensaje de usuario en la conversación. El audio se transcribe si input_audio_transcription está configurado para la sesión.

Cuando está en modo VAD de servidor, el cliente no necesita enviar este evento, el servidor hace commit automático del búfer de audio. Sin VAD del servidor, el cliente debe comprometer el búfer de audio para crear un elemento de mensaje de usuario. Este evento cliente produce un error si el búfer de audio de entrada está vacío.

Hacer commit del búfer de audio de entrada no genera una respuesta desde el modelo.

El servidor responde con un input_audio_buffer.committed evento.

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

La API de Voice Live envía los siguientes eventos del servidor para comunicar estado, respuestas y datos al cliente:

session.created

Se envía cuando se establece con éxito una nueva sesión. Este es el primer evento recibido tras conectarse a la API.

Event Structure

{
  "type": "session.created",
  "session": {
    "id": "sess_ABC123DEF456",
    "object": "realtime.session",
    "model": "gpt-realtime",
    "modalities": ["text", "audio"],
    "instructions": "You are a helpful assistant.",
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Properties

session.updated

Se envía cuando la configuración de la sesión se actualiza correctamente en respuesta a un session.update evento del cliente.

Event Structure

{
  "type": "session.updated",
  "session": {
    "id": "sess_ABC123DEF456",
    "voice": {
      "type": "azure-custom",
      "name": "my-voice",
      "endpoint_id": "12345678-1234-1234-1234-123456789012"
    },
    "temperature": 0.7,
    "avatar": {
      "character": "lisa",
      "customized": false
    }
  }
}

Properties

session.avatar.connecting

Indica que se está estableciendo una conexión avatar con WebRTC. Este evento se envía en respuesta a un session.avatar.connect evento de un cliente.

Event Structure

{
  "type": "session.avatar.connecting",
  "server_sdp": "<server_sdp>"
}

Properties

conversation.item.created

Se envía cuando se añade un nuevo elemento a la conversación, ya sea a través de un evento del cliente conversation.item.create o automáticamente durante la generación de respuestas.

Event Structure

{
  "type": "conversation.item.created",
  "previous_item_id": "item_ABC123",
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Hello, how are you?"
      }
    ]
  }
}

Properties

Ejemplo con elemento de audio

{
  "type": "conversation.item.created",
  "item": {
    "id": "item_GHI789",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_audio",
        "audio": null,
        "transcript": "What's the weather like today?"
      }
    ]
  }
}

conversation.item.retrieved

Enviado en respuesta a un conversation.item.retrieve evento del cliente, proporcionando el elemento de conversación solicitado.

Event Structure

{
  "type": "conversation.item.retrieved",
  "item": {
    "id": "item_ABC123",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "audio",
        "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA=",
        "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      }
    ]
  }
}

Properties

conversation.item.truncated

El evento del servidor conversation.item.truncated se devuelve cuando el cliente trunca un elemento anterior de un mensaje de audio asistente con un conversation.item.truncate evento. Este evento se utiliza para sincronizar la comprensión del audio del servidor con la reproducción del cliente.

Este evento trunca el audio y elimina la transcripción del texto del servidor para asegurar que no haya texto en el contexto que el usuario no conozca.

Event structure

{
  "type": "conversation.item.truncated",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

Properties

conversation.item.deleted

Enviado en respuesta a un conversation.item.delete evento del cliente, confirmando que el elemento especificado ha sido eliminado de la conversación.

Event Structure

{
  "type": "conversation.item.deleted",
  "item_id": "item_ABC123"
}

Properties

response.created

Se envía cuando comienza una nueva generación de respuesta. Este es el primer evento en una secuencia de respuesta.

Event Structure

{
  "type": "response.created",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "in_progress",
    "status_details": null,
    "output": [],
    "usage": {
      "total_tokens": 0,
      "input_tokens": 0,
      "output_tokens": 0
    }
  }
}

Properties

response.done

Se envía cuando la generación de respuestas está completa. Este evento contiene la respuesta final con todos los ítems de salida y estadísticas de uso.

Event Structure

{
  "type": "response.done",
  "response": {
    "id": "resp_ABC123",
    "object": "realtime.response",
    "status": "completed",
    "status_details": null,
    "output": [
      {
        "id": "item_DEF456",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 87,
      "input_tokens": 52,
      "output_tokens": 35,
      "input_token_details": {
        "cached_tokens": 0,
        "text_tokens": 45,
        "audio_tokens": 7
      },
      "output_token_details": {
        "text_tokens": 15,
        "audio_tokens": 20
      }
    }
  }
}

Properties

response.output_item.added

Se envía cuando se añade un nuevo elemento de salida a la respuesta durante la generación.

Event Structure

{
  "type": "response.output_item.added",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

Properties

response.output_item.done

Se envía cuando un elemento de salida está completo.

Event Structure

{
  "type": "response.output_item.done",
  "response_id": "resp_ABC123",
  "output_index": 0,
  "item": {
    "id": "item_DEF456",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm doing well, thank you for asking."
      }
    ]
  }
}

Properties

response.content_part.added

El evento del servidor response.content_part.added se devuelve cuando se añade una nueva parte de contenido a un elemento de mensaje asistente durante la generación de respuestas.

Event Structure

{
  "type": "response.content_part.added",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": ""
  }
}

Properties

response.content_part.done

El evento del servidor response.content_part.done se devuelve cuando una parte de contenido termina de transmitirse en un elemento de mensaje asistente.

Este evento también se devuelve cuando una respuesta se interrumpe, es incompleta o se cancela.

Event Structure

{
  "type": "response.content_part.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "text",
    "text": "Hello! I'm doing well, thank you for asking."
  }
}

Properties

response.text.delta

Streaming de contenido textual desde el modelo. Se envía de forma incremental a medida que el modelo genera texto.

Event Structure

{
  "type": "response.text.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm"
}

Properties

response.text.done

Se envía cuando la generación de contenido de texto está completa.

Event Structure

{
  "type": "response.text.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "text": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Properties

response.audio.delta

Streaming de audio desde el modelo. El audio se proporciona como datos codificados en base64.

Event Structure

{
  "type": "response.audio.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
}

Properties

response.audio.done

Se envía cuando la generación de contenido de audio está completa.

Event Structure

{
  "type": "response.audio.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

response.audio_transcript.delta

Transcripción en streaming del contenido de audio generado.

Event Structure

{
  "type": "response.audio_transcript.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "delta": "Hello! I'm doing"
}

Properties

response.audio_transcript.done

Se envía cuando la generación de transcripciones de audio esté completa.

Event Structure

{
  "type": "response.audio_transcript.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "transcript": "Hello! I'm doing well, thank you for asking. How can I help you today?"
}

Properties

conversation.item.input_audio_transcription.completed

El evento del servidor conversation.item.input_audio_transcription.completed es el resultado de la transcripción de audio para el habla escrita en el búfer de audio.

La transcripción comienza cuando el cliente o servidor (en server_vad modo) compromete el búfer de audio de entrada. La transcripción se ejecuta de forma asíncrona con la creación de respuestas, por lo que este evento puede ocurrir antes o después de los eventos de respuesta.

Los modelos API en tiempo real aceptan audio de forma nativa, por lo que la transcripción de entrada es un proceso separado que se ejecuta sobre un modelo de reconocimiento de voz distinto como whisper-1. Así, la transcripción puede divergir algo de la interpretación del modelo y debe tratarse como una guía aproximada.

Event structure

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "<item_id>",
  "content_index": 0,
  "transcript": "<transcript>"
}

Properties

conversation.item.input_audio_transcription.delta

El evento del servidor conversation.item.input_audio_transcription.delta se devuelve cuando se configura la transcripción de audio de entrada y se realiza una solicitud de transcripción para un mensaje de usuario. Este evento proporciona resultados parciales de transcripción a medida que están disponibles.

Event structure

{
  "type": "conversation.item.input_audio_transcription.delta",
  "item_id": "<item_id>",
  "content_index": 0,
  "delta": "<delta>"
}

Properties

conversation.item.input_audio_transcription.failed

El evento del servidor conversation.item.input_audio_transcription.failed se devuelve cuando se configura la transcripción de audio de entrada y falla una solicitud de transcripción para un mensaje de usuario. Este evento es independiente de otros error eventos para que el cliente pueda identificar el elemento relacionado.

Event structure

{
  "type": "conversation.item.input_audio_transcription.failed",
  "item_id": "<item_id>",
  "content_index": 0,
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Properties

Error properties

response.animation_blendshapes.delta

El evento del servidor response.animation_blendshapes.delta se devuelve cuando el modelo genera datos de blendshapes de animación como parte de una respuesta. Este evento proporciona datos incrementales de blendshapes a medida que están disponibles.

Event structure

{
  "type": "response.animation_blendshapes.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "frame_index": 0,
  "frames": [
    [0.0, 0.1, 0.2, ..., 1.0]
    ...
  ]
}

Properties

response.animation_blendshapes.done

El evento del servidor response.animation_blendshapes.done se devuelve cuando el modelo ha terminado de generar los datos de blendshapes de animación como parte de una respuesta.

Event structure

{
  "type": "response.animation_blendshapes.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
}

Properties

response.audio_timestamp.delta

El evento del servidor response.audio_timestamp.delta se devuelve cuando el modelo genera datos de marca de tiempo de audio como parte de una respuesta. Este evento proporciona datos incrementales de marca temporal para la alineación de audio y texto de salida a medida que está disponible.

Event structure

{
  "type": "response.audio_timestamp.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "audio_duration_ms": 500,
  "text": "Hello",
  "timestamp_type": "word"
}

Properties

response.audio_timestamp.done

Se envía cuando la generación de la marca de tiempo de audio está completa.

Event Structure

{
  "type": "response.audio_timestamp.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

response.animation_viseme.delta

El evento del servidor response.animation_viseme.delta se devuelve cuando el modelo genera datos de visemas de animación como parte de una respuesta. Este evento proporciona datos incrementales de visema a medida que están disponibles.

Event Structure

{
  "type": "response.animation_viseme.delta",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0,
  "audio_offset_ms": 0,
  "viseme_id": 1
}

Properties

response.animation_viseme.done

El evento del servidor response.animation_viseme.done se devuelve cuando el modelo ha terminado de generar datos de visemas de animación como parte de una respuesta.

Event Structure

{
  "type": "response.animation_viseme.done",
  "response_id": "resp_ABC123",
  "item_id": "item_DEF456",
  "output_index": 0,
  "content_index": 0
}

Properties

error

El evento del servidor error se devuelve cuando ocurre un error, que puede ser un problema del cliente o del servidor. La mayoría de los errores son recuperables y la sesión permanece abierta.

Event structure

{
  "type": "error",
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>",
    "event_id": "<event_id>"
  }
}

Properties

Error properties

warning

El evento del servidor warning se devuelve cuando ocurre una advertencia que no interrumpe el flujo de conversación. Las advertencias son informativas y la sesión continúa con normalidad.

Event structure

{
  "type": "warning",
  "warning": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

Properties

Warning properties

input_audio_buffer.cleared

El evento del servidor input_audio_buffer.cleared se devuelve cuando el cliente borra el búfer de audio de entrada con un input_audio_buffer.clear evento.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

El evento del servidor input_audio_buffer.committed se devuelve cuando se compromete un búfer de audio de entrada, ya sea por el cliente o automáticamente en modo VAD del servidor. La item_id propiedad es el ID del elemento de mensaje de usuario creado. Así, también se envía un conversation.item.created evento al cliente.

Event structure

{
  "type": "input_audio_buffer.committed",
  "previous_item_id": "<previous_item_id>",
  "item_id": "<item_id>"
}

Properties

input_audio_buffer.speech_started

El evento del servidor input_audio_buffer.speech_started se devuelve en server_vad modo cuando se detecta la voz en el búfer de audio. Este evento puede ocurrir en cualquier momento en que se añada audio al búfer (a menos que ya se haya detectado el habla).

El cliente debe esperar recibir un input_audio_buffer.speech_stopped evento cuando el habla se detiene. La item_id propiedad es el ID del elemento del mensaje de usuario creado cuando el habla se detiene. También item_id se incluye en el input_audio_buffer.speech_stopped evento a menos que el cliente comprometa manualmente el búfer de audio durante la activación del VAD.

Event structure

{
  "type": "input_audio_buffer.speech_started",
  "audio_start_ms": 0,
  "item_id": "<item_id>"
}

Properties

input_audio_buffer.speech_stopped

El evento del servidor input_audio_buffer.speech_stopped se devuelve en server_vad modo cuando el servidor detecta el fin del habla en el búfer de audio.

El servidor también envía un conversation.item.created evento con el elemento de mensaje de usuario creado a partir del búfer de audio.

Event structure

{
  "type": "input_audio_buffer.speech_stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

Properties

rate_limits.updated

El evento del servidor rate_limits.updated se emite al inicio de una respuesta para indicar los límites de velocidad actualizados.

Cuando se crea una respuesta, algunos tokens se reservan para los tokens de salida. Los límites de tarifa que se muestran aquí reflejan esa reserva, que luego se ajusta en consecuencia una vez completada la respuesta.

Event structure

{
  "type": "rate_limits.updated",
  "rate_limits": [
    {
      "name": "<name>",
      "limit": 0,
      "remaining": 0,
      "reset_seconds": 0
    }
  ]
}

Properties

response.audio.delta

El evento del servidor response.audio.delta se devuelve cuando se actualiza el audio generado por el modelo.

Event structure

{
  "type": "response.audio.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.audio.done

El evento del servidor response.audio.done se devuelve cuando el audio generado por el modelo está completo.

Este evento también se devuelve cuando una respuesta se interrumpe, es incompleta o se cancela.

Event structure

{
  "type": "response.audio.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

Properties

response.audio_transcript.delta

El evento del servidor response.audio_transcript.delta se devuelve cuando se actualiza la transcripción generada por el modelo de la salida de audio.

Event structure

{
  "type": "response.audio_transcript.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.audio_transcript.done

El evento del servidor response.audio_transcript.done se devuelve cuando la transcripción generada por el modelo de la salida de audio termina de transmitir.

Este evento también se devuelve cuando una respuesta se interrumpe, es incompleta o se cancela.

Event structure

{
  "type": "response.audio_transcript.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "transcript": "<transcript>"
}

Properties

response.function_call_arguments.delta

El evento del servidor response.function_call_arguments.delta se devuelve cuando se actualizan los argumentos de la llamada a función generados por el modelo.

Event structure

{
  "type": "response.function_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "delta": "<delta>"
}

Properties

response.function_call_arguments.done

El evento del servidor response.function_call_arguments.done se devuelve cuando los argumentos de la llamada a la función generados por el modelo terminan de transmitirse.

Este evento también se devuelve cuando una respuesta se interrumpe, es incompleta o se cancela.

Event structure

{
  "type": "response.function_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "arguments": "<arguments>"
}

Properties

mcp_list_tools.in_progress

El evento del servidor mcp_list_tools.in_progress se devuelve cuando el servicio empieza a listar las herramientas disponibles de un servidor mcp.

Event structure

{
  "type": "mcp_list_tools.in_progress",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

mcp_list_tools.completed

El evento del servidor mcp_list_tools.completed se devuelve cuando el servicio completa de listar las herramientas disponibles de un servidor mcp.

Event structure

{
  "type": "mcp_list_tools.completed",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

mcp_list_tools.failed

El evento del servidor mcp_list_tools.failed se devuelve cuando el servicio no lista las herramientas disponibles de un servidor mcp.

Event structure

{
  "type": "mcp_list_tools.failed",
  "item_id": "<mcp_list_tools_item_id>"
}

Properties

response.mcp_call_arguments.delta

El evento del servidor response.mcp_call_arguments.delta se devuelve cuando se actualizan los argumentos de llamada a la herramienta mcp generados por el modelo.

Event structure

{
  "type": "response.mcp_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "delta": "<delta>"
}

Properties

response.mcp_call_arguments.done

El evento del servidor response.mcp_call_arguments.done se devuelve cuando los argumentos de llamada a la herramienta mcp generados por el modelo terminan de transmitirse.

Event structure

{
  "type": "response.mcp_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "arguments": "<arguments>"
}

Properties

response.mcp_call.in_progress

El evento del servidor response.mcp_call.in_progress se devuelve cuando una llamada a una herramienta MCP comienza a procesarse.

Event structure

{
  "type": "response.mcp_call.in_progress",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.mcp_call.completed

El evento del servidor response.mcp_call.completed se devuelve cuando una llamada a la herramienta MCP se completa con éxito.

Event structure

{
  "type": "response.mcp_call.completed",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.mcp_call.failed

El evento del servidor response.mcp_call.failed se devuelve cuando falla una llamada a una herramienta MCP.

Event structure

{
  "type": "response.mcp_call.failed",
  "item_id": "<item_id>",
  "output_index": 0
}

Properties

response.output_item.added

El evento del servidor response.output_item.added se devuelve cuando se crea un nuevo elemento durante la generación de respuestas.

Event structure

{
  "type": "response.output_item.added",
  "response_id": "<response_id>",
  "output_index": 0
}

Properties

response.output_item.done

El evento del servidor response.output_item.done se devuelve cuando un elemento termina de transmitirse.

Este evento también se devuelve cuando una respuesta se interrumpe, es incompleta o se cancela.

Event structure

{
  "type": "response.output_item.done",
  "response_id": "<response_id>",
  "output_index": 0
}

Properties

response.text.delta

El evento del servidor response.text.delta se devuelve cuando se actualiza el texto generado por el modelo. El texto corresponde a la text parte de contenido de un elemento de mensaje asistente.

Event structure

{
  "type": "response.text.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

Properties

response.text.done

El evento del servidor response.text.done se devuelve cuando el texto generado por el modelo termina de transmitirse. El texto corresponde a la text parte de contenido de un elemento de mensaje asistente.

Este evento también se devuelve cuando una respuesta se interrumpe, es incompleta o se cancela.

Event structure

{
  "type": "response.text.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "text": "<text>"
}

Properties

Components

Audio Formats

RealtimeAudioFormat

Formato base de audio usado para audio de entrada.

Allowed Values:

• pcm16 - Formato de audio PCM de 16 bits
• g711_ulaw - Formato de audio G.711 μ-law
• g711_alaw - Formato de audio G.711 A-law

RealtimeOutputAudioFormat

Formato de audio utilizado para audio de salida con tasas de muestreo específicas.

Allowed Values:

• pcm16 - Formato de audio PCM de 16 bits a la frecuencia de muestreo predeterminada (24kHz)
• pcm16_8000hz - Formato de audio PCM de 16 bits a una tasa de muestreo de 8kHz
• pcm16_16000hz - Formato de audio PCM de 16 bits a tasa de muestreo de 16kHz
• g711_ulaw - Formato de audio G.711 μ-law (mu-law) a una frecuencia de muestreo de 8kHz
• g711_alaw - Formato de audio G.711 A-law a 8kHz de tasa de muestreo

RealtimeAudioInputTranscriptionSettings

Configuración para transcripción de audio de entrada.

RealtimeInputAudioNoiseReductionSettings

Esto puede ser:

• Un objeto RealtimeOpenAINoiseReduction
• Un objeto RealtimeAzureDeepNoiseSuppression

RealtimeOpenAINoiseReduction

Configuración de reducción de ruido OpenAI con campo de tipo explícito, disponible solo para gpt-realtime modelos y gpt-realtime-mini

RealtimeAzureDeepNoiseSuppression

Configuración para la reducción de ruido de audio de entrada.

RealtimeInputAudioEchoCancellationSettings

Configuración de cancelación de eco para procesamiento de audio en servidor.

Voice Configuration

RealtimeVoice

Unión de todas las configuraciones de voz soportadas.

Esto puede ser:

• Un objeto RealtimeOpenAIVoice
• Un objeto RealtimeAzureVoice

RealtimeOpenAIVoice

Configuración de voz OpenAI con campo de tipo explícito.

RealtimeAzureVoice

Base para configuraciones de voz en Azure. Se trata de una unión discriminada con diferentes tipos:

RealtimeAzureStandardVoice

Configuración estándar de voz de Azure.

RealtimeAzureCustomVoice

Configuración de voz personalizada de Azure (preferida para voces personalizadas).

Example:

{
  "type": "azure-custom",
  "name": "my-custom-voice",
  "endpoint_id": "12345678-1234-1234-1234-123456789012",
  "temperature": 0.7,
  "style": "cheerful",
  "locale": "en-US"
}

RealtimeAzurePersonalVoice

Azure personal voice configuration.

Turn Detection

RealtimeTurnDetection

Configuración para detección de giros. Se trata de un sindicato discriminado que soporta múltiples tipos de DAV.

RealtimeServerVAD

Detección de giro basada en VAD base.

RealtimeOpenAISemanticVAD

Configuración semántica VAD de OpenAI, que utiliza un modelo para determinar cuándo el usuario ha terminado de hablar. Solo disponible para gpt-realtime modelos.gpt-realtime-mini

RealtimeAzureSemanticVAD

Azure Semantic VAD, que determina cuándo el usuario inicia y habla usando un modelo semántico de voz, proporcionando una detección más robusta en entornos ruidosos.

RealtimeAzureSemanticVADMultilingual

Azure semantic VAD (variante por defecto).

RealtimeEOUDetection

Azure End-of-Utterance (EOU) podría indicar cuándo el usuario final dejó de hablar, permitiendo pausas naturales. La detección de fin de enunciación puede reducir significativamente los intermitentes prematuros al final de giro sin añadir latencia perceptible por el usuario.

Avatar Configuration

RealtimeAvatarConfig

Configuración para el streaming y comportamiento del avatar.

RealtimeIceServer

Configuración del servidor ICE para la negociación de conexiones WebRTC.

RealtimeVideoParams

Parámetros de transmisión de vídeo para Avatar.

RealtimeVideoCrop

Definición de rectángulo de recorte en vídeo.

RealtimeVideoResolution

Especificación de resolución de vídeo.

RealtimeAvatarScene

Configuración para el nivel de zoom, posición, rotación y amplitud de movimiento del avatar en el fotograma de vídeo.

Animation Configuration

RealtimeAnimation

Configuración para salidas de animación incluyendo blendshapes y visemas.

RealtimeAnimationOutputType

Tipos de datos de animación para exportar.

Allowed Values:

• blendshapes - Datos de blendshapes faciales
• viseme_id - Datos de identificador de Viseme

Session Configuration

RealtimeRequestSession

Objeto de configuración de sesión usado en session.update eventos.

RealtimeModality

Soportaba modalidades de salida de sesión.

Allowed Values:

• text - Salida de texto
• audio - Salida de audio
• animation - Producción de animación
• avatar - Salida de vídeo Avatar

RealtimeAudioTimestampType

Tipos de marca de tiempo de salida soportados en contenido de respuesta de audio.

Allowed Values:

• word - Marcas de tiempo por palabra en el audio de salida

ReasoningEffort

Restringe el esfuerzo en el razonamiento para modelos de razonamiento. Consulta la documentación del modelo para ver si hay valores compatibles con cada modelo. Reducir el esfuerzo de razonamiento puede resultar en respuestas más rápidas y menos tokens usados en el razonamiento en una respuesta.

Allowed Values:

• none - Sin esfuerzo de razonamiento
• minimal - Esfuerzo mínimo de razonamiento
• low - Bajo esfuerzo de razonamiento: respuestas más rápidas con menos razonamiento
• medium - Esfuerzo de razonamiento medio - equilibrado entre velocidad y profundidad de razonamiento
• high - Alto esfuerzo de razonamiento: razonamiento más completo, puede llevar más tiempo
• xhigh - Esfuerzo de razonamiento extra alto - máxima profundidad de razonamiento

Tool Configuration

Somos compatibles con dos tipos de herramientas: llamadas de funciones y herramientas MCP, que permiten conectarte a un servidor MCP.

RealtimeTool

Definición de herramienta para la llamada a funciones.

RealtimeToolChoice

Estrategia de selección de herramientas.

Esto puede ser:

• "auto" - Que el modelo elija
• "none" - No uses herramientas
• "required" - Debe usar una herramienta
• { "type": "function", "name": "function_name" } - Usar funciones específicas

MCPTool

Configuración de la herramienta MCP.

RealtimeConversationResponseItem

Este es un tipo de unión que puede ser uno de los siguientes:

RealtimeConversationUserMessageItem

Mensaje de usuario.

RealtimeConversationAssistantMessageItem

Elemento del mensaje del asistente.

RealtimeConversationSystemMessageItem

Elemento del mensaje del sistema.

RealtimeConversationFunctionCallItem

Elemento de solicitud de llamada de función.

RealtimeConversationFunctionCallOutputItem

Elemento de respuesta de llamada funcional.

RealtimeConversationMCPListToolsItem

MCP lista herramientas de respuesta.

RealtimeConversationMCPCallItem

Ítem de respuesta de llamada MCP.

RealtimeConversationMCPApprovalRequestItem

Solicitud de aprobación del MCP ítem.

RealtimeItemStatus

Estado de los temas de conversación.

Allowed Values:

• in_progress - Actualmente en proceso
• completed - Completado con éxito
• incomplete - Incompleto (interrumpido o fallido)

RealtimeContentPart

Parte de contenido dentro de un mensaje.

RealtimeInputTextContentPart

Parte del contenido de texto.

RealtimeOutputTextContentPart

Parte del contenido de texto.

RealtimeInputAudioContentPart

Parte de contenido de audio.

RealtimeOutputAudioContentPart

Parte de contenido de audio.

Response Objects

RealtimeResponse

Objeto respuesta que representa una respuesta de inferencia modelo.

RealtimeResponseStatus

Valores de estado de respuesta.

Allowed Values:

• in_progress - Se está generando respuesta
• completed - Respuesta completada con éxito
• canceled - La respuesta fue cancelada
• incomplete - Respuesta incompleta (interrumpida)
• failed - Respuesta fallida con error

RealtimeUsage

Estadísticas de uso de tokens.

TokenDetails

Desglose detallado del uso de los tokens.

Error Handling

RealtimeErrorDetails

Objeto de información de error.

RealtimeConversationRequestItem

Usas el RealtimeConversationRequestItem objeto para crear un nuevo elemento en la conversación a través del evento conversation.item.create .

Este es un tipo de unión que puede ser uno de los siguientes:

RealtimeSystemMessageItem

Un elemento de mensaje del sistema.

RealtimeUserMessageItem

Un mensaje de usuario.

RealtimeAssistantMessageItem

Un mensaje de asistente.

RealtimeFunctionCallItem

Un elemento de llamada de función.

RealtimeFunctionCallOutputItem

Una función llama a elemento de salida.

RealtimeMCPApprovalResponseItem

Un elemento de respuesta de aprobación del MCP.

RealtimeFunctionTool

La definición de una herramienta de función tal como la utiliza el endpoint en tiempo real.

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

El RealtimeResponseSession objeto representa una sesión en la API en tiempo real. Se utiliza en algunos eventos del servidor, como:

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

• Prueba el inicio rápido de Voice Live
• Prueba el inicio rápido de los agentes de Voice Live
• Más información sobre cómo usar Voice Live API