Referencia de Voice Live 2025-10-01 API

Voice Live API proporciona comunicación bidireccional en tiempo real para aplicaciones habilitadas para voz mediante conexiones WebSocket. Esta API admite características avanzadas, como el reconocimiento de voz, la síntesis de texto a voz, el streaming de avatares, los datos de animación y las funcionalidades completas de procesamiento de audio.

La API usa eventos con formato JSON enviados a través de conexiones de WebSocket para administrar conversaciones, secuencias de audio, interacciones de avatar y respuestas en tiempo real. Los eventos se clasifican en eventos de cliente (enviados de cliente a servidor) y eventos de servidor (enviados desde el servidor al cliente).

Key Features

• Procesamiento de audio en tiempo real: compatibilidad con varios formatos de audio, incluidos PCM16 a varias velocidades de muestreo y códecs G.711
• Opciones avanzadas de voz: voces de OpenAI, voces personalizadas de Azure, voces estándar de Azure y voces personales de Azure
• Integración de Avatar: streaming de avatares basado en WebRTC con vídeo, animación y blendshapes
• Detección de turnos inteligentes: varias opciones de VAD, como vaD semántico de Azure y detección del lado servidor
• Mejora de audio: reducción de ruido integrada y cancelación de eco
• Llamada a funciones: integración de herramientas para funcionalidades de conversación mejoradas
• Administración flexible de sesiones: modalidades de salida configurables, instrucciones y parámetros de respuesta

Client Events

Voice Live API admite los siguientes eventos de cliente que se pueden enviar desde el cliente al servidor:

session.update

Actualice la configuración de la sesión. Este evento se puede enviar en cualquier momento para modificar la configuración, como voz, modalidades de salida, detección de turnos, herramientas y otros parámetros de sesión. Tenga en cuenta que una vez que se inicializa una sesión con un modelo determinado, no se puede cambiar 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 Voz personalizada de Azure

{
  "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

Establezca una conexión de avatar proporcionando la oferta SDP (Protocolo de descripción de sesión) del cliente para la negociación de medios webRTC. Este evento es necesario cuando se usan características de avatar.

Event Structure

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

Properties

input_audio_buffer.append

Anexe bytes de audio al búfer de audio de entrada.

Event Structure

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

Properties

input_audio_buffer.commit

Confirme el búfer de audio de entrada para su procesamiento.

Event Structure

{
  "type": "input_audio_buffer.commit"
}

Properties

input_audio_buffer.clear

Borre el búfer de audio de entrada.

Event Structure

{
  "type": "input_audio_buffer.clear"
}

Properties

conversation.item.create

Agregue un nuevo elemento al contexto de conversación. Esto puede incluir mensajes, llamadas de función y respuestas de llamadas de función. Los elementos se pueden insertar en posiciones específicas en el historial de conversaciones.

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 de 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 de MCP

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

conversation.item.retrieve

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

Event Structure

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

Properties

conversation.item.truncate

Trunca el contenido de audio de un mensaje del asistente. Esto resulta ú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

Quite un elemento del historial de conversaciones.

Event Structure

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

Properties

response.create

Indique al servidor que cree una respuesta a través de la inferencia del modelo. Este evento puede especificar la configuración específica de la respuesta que invalida 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 opció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

Cancelar 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 de cliente input_audio_buffer.append se usa para anexar bytes de audio al búfer de audio de entrada. El búfer de audio es almacenamiento temporal en el que puede escribir y confirmarse posteriormente.

En el modo VAD del servidor (detección de actividad de voz), el búfer de audio se usa para detectar voz y el servidor decide cuándo confirmar. Cuando el VAD del servidor está deshabilitado, el cliente puede elegir la cantidad de audio que se va a colocar en cada evento hasta un máximo de 15 MiB. Por ejemplo, transmitir fragmentos más pequeños del cliente puede permitir que el VAD tenga mayor capacidad de respuesta.

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

Event structure

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

Properties

input_audio_buffer.clear

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

El servidor responde con un evento input_audio_buffer.cleared.

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

input_audio_buffer.commit

El evento de cliente input_audio_buffer.commit se usa 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 confirma automáticamente el búfer de audio. Sin VAD del servidor, el cliente debe confirmar el búfer de audio para crear un elemento de mensaje de usuario. Este evento de cliente produce un error si el búfer de audio de entrada está vacío.

Confirmar el búfer de audio de entrada no crea una respuesta del modelo.

El servidor responde con un evento input_audio_buffer.committed.

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Server Events

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

session.created

Se envía cuando se establece correctamente una nueva sesión. Este es el primer evento recibido después de 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 sesión se actualiza correctamente en respuesta a un session.update evento de 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 WebRTC de avatar. Este evento se envía en respuesta a un session.avatar.connect evento de cliente.

Event Structure

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

Properties

conversation.item.created

Se envía cuando se agrega un nuevo elemento a la conversación, ya sea a través de un evento de 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

Se envía en respuesta a un conversation.item.retrieve evento de 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 de servidor conversation.item.truncated se devuelve cuando el cliente trunca un elemento de mensaje de audio del asistente anterior con un evento conversation.item.truncate. Este evento se usa para sincronizar la comprensión del servidor del audio con la reproducción del cliente.

Este evento trunca el audio y quita la transcripción de texto del lado servidor para asegurarse de que no hay texto en el contexto del que el usuario no conoce.

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 de cliente, confirmando que el elemento especificado se ha quitado 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 respuestas. Este es el primer evento de 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 se completa la generación de respuestas. Este evento contiene la respuesta final con todos los elementos 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 agrega 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 se completa un elemento de salida.

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 de servidor response.content_part.added se devuelve cuando se agrega una nueva parte de contenido a un elemento de mensaje del 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 de servidor response.content_part.done se devuelve cuando una parte del contenido ha terminado de transmitirse en un elemento de mensaje del asistente.

Este evento también se devuelve cuando una respuesta se interrumpe, queda 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 de texto desde el modelo. Enviado incrementalmente 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 se completa la generación de contenido de texto.

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 contenido 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 se completa la generación de contenido de audio.

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 de 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 se completa la generación de transcripciones de audio.

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 de servidor conversation.item.input_audio_transcription.completed es el resultado de la transcripción de audio para la voz escrita en el búfer de audio.

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

Los modelos de API en tiempo real aceptan audio de forma nativa y, por tanto, la transcripción de entrada es una ejecución de proceso independiente en un modelo de reconocimiento de voz independiente, como whisper-1. Por lo tanto, la transcripción puede diferir 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 de servidor conversation.item.input_audio_transcription.delta se devuelve cuando se configura la transcripción de audio de entrada y hay una solicitud de transcripción para un mensaje de usuario en curso. 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 de servidor conversation.item.input_audio_transcription.failed se devuelve cuando se configura la transcripción de audio de entrada y se produce un error en una solicitud de transcripción para un mensaje de usuario. Este evento es independiente de otros eventos error 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 de servidor response.animation_blendshapes.delta se devuelve cuando el modelo genera datos blendshapes de animación como parte de una respuesta. Este evento proporciona datos de blendshapes incrementales a medida que está disponible.

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 de servidor response.animation_blendshapes.done se devuelve cuando el modelo ha terminado de generar 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 de 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 de tiempo 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 se completa la generación de marca de tiempo de audio.

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 de servidor response.animation_viseme.delta se devuelve cuando el modelo genera datos de viseme de animación como parte de una respuesta. Este evento proporciona datos viseme incrementales a medida que está disponible.

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 de servidor response.animation_viseme.done se devuelve cuando el modelo ha terminado de generar datos de viseme 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 de servidor error se devuelve cuando se produce un error, que podría ser un problema de cliente o un problema de servidor. La mayoría de los errores se pueden recuperar 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 de servidor warning se devuelve cuando se produce una advertencia que no interrumpe el flujo de conversación. Las advertencias son informativas y la sesión continúa normalmente.

Event structure

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

Properties

Warning properties

input_audio_buffer.cleared

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

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

input_audio_buffer.committed

El evento de servidor input_audio_buffer.committed se devuelve cuando un búfer de audio de entrada se confirma, ya sea por el cliente o de forma automática en el modo VAD de servidor. La propiedad item_id es el identificador del elemento de mensaje de usuario creado. Por lo tanto, también se envía un evento conversation.item.created 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 de servidor input_audio_buffer.speech_started se devuelve en modo server_vad cuando se detecta voz en el búfer de audio. Este evento puede ocurrir cada vez que se agrega audio al búfer (a menos que ya se detecte voz).

El cliente debe esperar recibir un evento input_audio_buffer.speech_stopped cuando se detiene la voz. La propiedad item_id es el id. del elemento de mensaje de usuario creado cuando se detiene la voz. El item_id también se incluye en el evento input_audio_buffer.speech_stopped a menos que el cliente confirme manualmente el búfer de audio durante la activación de 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 de servidor input_audio_buffer.speech_stopped se devuelve en modo server_vad cuando el servidor detecta el final de la voz en el búfer de audio.

El servidor también envía un evento conversation.item.created 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 de servidor rate_limits.updated se emite al principio 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 velocidad que se muestran aquí reflejan esa reserva, que 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 de 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 de servidor response.audio.done se devuelve cuando se realiza el audio generado por el modelo.

Este evento también se devuelve cuando una respuesta se interrumpe, queda 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 de servidor response.audio_transcript.delta se devuelve cuando se actualiza la transcripción generada por el modelo de 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 de servidor response.audio_transcript.done se devuelve cuando la transcripción generada por el modelo de salida de audio ya ha terminado de transmitirse.

Este evento también se devuelve cuando una respuesta se interrumpe, queda 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 de servidor response.function_call_arguments.delta se devuelve cuando se actualizan los argumentos de llamada de 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 de servidor response.function_call_arguments.done se devuelve cuando los argumentos de la llamada de función generados por el modelo han terminado de transmitirse.

Este evento también se devuelve cuando una respuesta se interrumpe, queda 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 de servidor mcp_list_tools.in_progress se devuelve cuando el servicio comienza a enumerar las herramientas disponibles desde 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 de servidor mcp_list_tools.completed se devuelve cuando el servicio completa la lista de 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 de servidor mcp_list_tools.failed se devuelve cuando el servicio no puede enumerar 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 de servidor response.mcp_call_arguments.delta se devuelve cuando se actualizan los argumentos de llamada de 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 de servidor response.mcp_call_arguments.done se devuelve cuando los argumentos de llamada a la herramienta mcp generados por el modelo se realizan streaming.

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 de servidor response.mcp_call.in_progress se devuelve cuando una llamada a la herramienta MCP comienza el procesamiento.

Event structure

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

Properties

response.mcp_call.completed

El evento de servidor response.mcp_call.completed se devuelve cuando una llamada a la herramienta MCP se completa correctamente.

Event structure

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

Properties

response.mcp_call.failed

El evento de servidor response.mcp_call.failed se devuelve cuando se produce un error en una llamada a la herramienta MCP.

Event structure

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

Properties

response.output_item.added

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

Event structure

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

Properties

response.output_item.done

El evento de servidor response.output_item.done se devuelve cuando un elemento ha terminado de transmitirse.

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

Event structure

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

Properties

response.text.delta

El evento de servidor response.text.delta se devuelve cuando se actualiza el texto generado por el modelo. El texto corresponde a la parte de contenido text de un elemento de mensaje del 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 de servidor response.text.done se devuelve cuando el texto generado por el modelo ha terminado de transmitirse. El texto corresponde a la parte de contenido text de un elemento de mensaje del asistente.

Este evento también se devuelve cuando una respuesta se interrumpe, queda 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 de audio base usado para el audio de entrada.

Allowed Values:

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

RealtimeOutputAudioFormat

Formato de audio usado para el audio de salida con velocidades de muestreo específicas.

Allowed Values:

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

RealtimeAudioInputTranscriptionSettings

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

RealtimeInputAudioNoiseReductionSettings

Esto puede ser:

• Objeto RealtimeOpenAINoiseReduction
• Un objeto RealtimeAzureDeepNoiseSuppression

RealtimeOpenAINoiseReduction

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

RealtimeAzureDeepNoiseSuppression

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

RealtimeInputAudioEchoCancellationSettings

Configuración de cancelación de eco para el procesamiento de audio del lado servidor.

Voice Configuration

RealtimeVoice

Unión de todas las configuraciones de voz admitidas.

Esto puede ser:

• Un objeto RealtimeOpenAIVoice
• Un objeto RealtimeAzureVoice

RealtimeOpenAIVoice

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

RealtimeAzureVoice

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

RealtimeAzureStandardVoice

Configuración de voz estándar 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

Configuración de voz personal de Azure.

Turn Detection

RealtimeTurnDetection

Configuración para la detección de turnos. Se trata de una unión discriminada que admite varios tipos VAD.

RealtimeServerVAD

Detección de turnos basada en VAD base.

RealtimeOpenAISemanticVAD

Configuración vaD semántica de OpenAI que usa un modelo para determinar cuándo el usuario ha terminado de hablar. Solo está disponible para gpt-realtime los modelos y gpt-realtime-mini .

RealtimeAzureSemanticVAD

VAD semántico de Azure, que determina cuándo se inicia y habla el usuario mediante un modelo de voz semántica, lo que proporciona una detección más sólida en entornos ruidosos.

RealtimeAzureSemanticVADMultilingual

VAD semántico de Azure (variante predeterminada).

RealtimeEOUDetection

Azure End-of-Utterance (EOU) podría indicar cuándo el usuario final dejó de hablar mientras permitía pausas naturales. La detección de finales de expresiones puede reducir significativamente las señales prematuras de fin de turno sin agregar latencia que se pueda percibir por el usuario.

Avatar Configuration

RealtimeAvatarConfig

Configuración para el streaming y el comportamiento del avatar.

RealtimeIceServer

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

RealtimeVideoParams

Parámetros de streaming de vídeo para avatar.

RealtimeVideoCrop

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

RealtimeVideoResolution

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

RealtimeAvatarScene

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

Animation Configuration

RealtimeAnimation

Configuración para las salidas de animación, incluidas blendshapes y visemes.

RealtimeAnimationOutputType

Tipos de datos de animación que se van a generar.

Allowed Values:

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

Session Configuration

RealtimeRequestSession

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

RealtimeModality

Modalidades de salida de sesión admitidas.

Allowed Values:

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

RealtimeAudioTimestampType

Tipos de marca de tiempo de salida admitidos en el 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 de los modelos de razonamiento. Consulte la documentación del modelo para ver los valores admitidos para cada modelo. Reducir el esfuerzo de razonamiento puede dar lugar a 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 exhaustivo, puede tardar más tiempo
• xhigh - Esfuerzo de razonamiento extra alto- profundidad de razonamiento máxima

Tool Configuration

Se admiten dos tipos de herramientas: llamadas a funciones y herramientas de MCP que permiten conectarse a un servidor mcp.

RealtimeTool

Definición de la herramienta para las llamadas a funciones.

RealtimeToolChoice

Estrategia de selección de herramientas.

Esto puede ser:

• "auto" - Permitir que el modelo elija
• "none" - No usar herramientas
• "required" - Debe usar una herramienta
• { "type": "function", "name": "function_name" } - Uso de una función específica

MCPTool

Configuración de la herramienta MCP.

RealtimeConversationResponseItem

Se trata de un tipo de unión que puede ser uno de los siguientes:

RealtimeConversationUserMessageItem

Elemento de mensaje de usuario.

RealtimeConversationAssistantMessageItem

Elemento de mensaje del asistente.

RealtimeConversationSystemMessageItem

Elemento de mensaje del sistema.

RealtimeConversationFunctionCallItem

Elemento de solicitud de llamada de función.

RealtimeConversationFunctionCallOutputItem

Elemento de respuesta de llamada de función.

RealtimeConversationMCPListToolsItem

Elemento de respuesta de las herramientas de lista de MCP.

RealtimeConversationMCPCallItem

Elemento de respuesta de llamada de MCP.

RealtimeConversationMCPApprovalRequestItem

Elemento de solicitud de aprobación de MCP.

RealtimeItemStatus

Estado de los elementos de conversación.

Allowed Values:

• in_progress - Actualmente se está procesando
• completed - Completado correctamente
• incomplete - Incompleto (interrumpido o erróneo)

RealtimeContentPart

Elemento de contenido dentro de un mensaje.

RealtimeInputTextContentPart

Elemento de contenido de texto.

RealtimeOutputTextContentPart

Elemento de contenido de texto.

RealtimeInputAudioContentPart

Elemento de contenido de audio.

RealtimeOutputAudioContentPart

Elemento de contenido de audio.

Response Objects

RealtimeResponse

Objeto de respuesta que representa una respuesta de inferencia de modelo.

RealtimeResponseStatus

Valores de estado de respuesta.

Allowed Values:

• in_progress - Se está generando la respuesta
• completed - Respuesta completada correctamente
• cancelled - Se canceló la respuesta
• incomplete - Respuesta incompleta (interrumpida)
• failed - Error de respuesta

RealtimeUsage

Estadísticas de uso de tokens.

TokenDetails

Desglose detallado del uso de tokens.

Error Handling

RealtimeErrorDetails

Objeto de información de error.

RealtimeConversationRequestItem

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

Se trata de un tipo de unión que puede ser uno de los siguientes:

RealtimeSystemMessageItem

Un elemento de mensaje del sistema.

RealtimeUserMessageItem

Un elemento de mensaje de usuario.

RealtimeAssistantMessageItem

Elemento de mensaje del asistente.

RealtimeFunctionCallItem

Un elemento de llamada de función.

RealtimeFunctionCallOutputItem

Un elemento de salida de llamada de función.

RealtimeMCPApprovalResponseItem

Un elemento de respuesta de aprobación de MCP.

RealtimeFunctionTool

Definición de una herramienta de función tal como la usa el punto de conexión en tiempo real.

RealtimeItemStatus

Allowed Values:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

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

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Related Resources

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