Leer en inglés

Compartir a través de


Referencia de API en tiempo real (versión preliminar)

Nota

Esta característica actualmente está en su versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

La API en tiempo real es una API basada en WebSocket que permite interactuar con el servicio Azure OpenAI en tiempo real.

La API en tiempo real (a través de /realtime) se basa en la API WebSockets para facilitar una comunicación en flujo totalmente asíncrona entre el usuario final y el modelo. Los detalles del dispositivo, como la captura y la representación de datos de audio, están fuera del ámbito de la API en tiempo real. Debe utilizarse en el contexto de un servicio intermedio de confianza que administre tanto las conexiones con los usuarios finales como las conexiones de los puntos de conexión modelo. No lo use directamente desde dispositivos de usuario final que no son de confianza.

Sugerencia

Para empezar a trabajar con la API en tiempo real, consulte la guía de inicio rápido y procedimientos.

Connection

La API en tiempo real requiere un punto de conexión de recurso de Azure OpenAI existente en una región admitida. Se accede a la API a través de una conexión segura de WebSocket al punto de conexión /realtime del recurso de Azure OpenAI.

Puede construir un URI de solicitud completa mediante la concatenación:

  • Protocolo WebSocket seguro (wss://).
  • El nombre de host de su punto de conexión de recursos Azure OpenAI, por ejemplo, my-aoai-resource.openai.azure.com
  • Ruta de acceso de la API de openai/realtime.
  • Un parámetro de cadena de consulta api-version para una versión de API compatible, como 2024-12-17
  • Parámetro de cadena de consulta deployment con el nombre de la implementación del modelo gpt-4o-realtime-preview o gpt-4o-mini-realtime-preview.

El ejemplo siguiente es un URI de solicitud bien construido /realtime:

wss://my-eastus2-openai-resource.openai.azure.com/openai/realtime?api-version=2024-12-17&deployment=gpt-4o-realtime-preview

Autenticación

Para autenticarse:

  • Microsoft Entra (recomendado): utilice la autenticación basada en token con la API /realtime para un recurso de Azure OpenAI Service con la identidad administrada habilitada. Aplicar un token de autenticación recuperado utilizando un token Bearer con el encabezado Authorization.
  • Clave API: un api-key se puede proporcionar de dos maneras:
    • Utilizar un encabezado de conexión api-key en la conexión prehandshake. Esta opción no está disponible en un entorno de navegador.
    • El uso de un parámetro de cadena de consulta api-key en la URI de solicitud. Los parámetros de cadena de consulta se cifran al usar https/wss.

Eventos de cliente

Hay nueve eventos de cliente que se pueden enviar desde el cliente al servidor:

Evento Descripción
RealtimeClientEventConversationItemCreate El evento de cliente conversation.item.create se usa para agregar un nuevo elemento al contexto de la conversación, incluidos los mensajes, las llamadas de función y las respuestas de llamada de función.
RealtimeClientEventConversationItemDelete El evento de cliente conversation.item.delete se usa para quitar un elemento del historial de conversaciones.
RealtimeClientEventConversationItemTruncate El evento de cliente conversation.item.truncate se usa para truncar el audio de un mensaje del asistente anterior.
RealtimeClientEventInputAudioBufferAppend El evento de cliente input_audio_buffer.append se usa para anexar bytes de audio al búfer de audio de entrada.
RealtimeClientEventInputAudioBufferClear El evento de cliente input_audio_buffer.clear se usa para borrar los bytes de audio en el búfer.
RealtimeClientEventInputAudioBufferCommit El evento de cliente input_audio_buffer.commit se usa para confirmar el búfer de audio de entrada del usuario.
RealtimeClientEventResponseCancel El evento de cliente response.cancel se usa para cancelar una respuesta en curso.
RealtimeClientEventResponseCreate El evento de cliente response.create se usa para indicar al servidor que cree una respuesta a través de la inferencia del modelo.
RealtimeClientEventSessionUpdate El evento de cliente session.update se usa para actualizar la configuración predeterminada de la sesión.

RealtimeClientEventConversationItemCreate

El evento de cliente conversation.item.create se usa para agregar un nuevo elemento al contexto de la conversación, incluidos los mensajes, las llamadas de función y las respuestas de llamada de función. Este evento se puede usar para rellenar un historial de la conversación y para agregar nuevos elementos a mitad de secuencia. Actualmente este evento no puede rellenar los mensajes de audio del asistente.

Si se ejecuta correctamente, el servidor responde con un evento conversation.item.created; de lo contrario, se envía un evento error.

Estructura de eventos

{
  "type": "conversation.item.create",
  "previous_item_id": "<previous_item_id>"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.item.create.
previous_item_id string Identificador del elemento anterior después del cual se inserta el nuevo elemento. Si no se establece, el nuevo elemento se anexa al final de la conversación. Si se establece, permite insertar un elemento a mitad de la conversación. Si no se encuentra el identificador, se devuelve un error y no se agrega el elemento.
item RealtimeConversationRequestItem Elemento que se va a agregar a la conversación.

RealtimeClientEventConversationItemDelete

El evento de cliente conversation.item.delete se usa para quitar un elemento del historial de conversaciones.

El servidor responde con un evento conversation.item.deleted, a menos que el elemento no exista en el historial de conversaciones, en cuyo caso el servidor responde con un error.

Estructura de eventos

{
  "type": "conversation.item.delete",
  "item_id": "<item_id>"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.item.delete.
item_id string Identificador del elemento que se va a eliminar.

RealtimeClientEventConversationItemTruncate

El evento de cliente conversation.item.truncate se usa para truncar el audio de un mensaje del asistente anterior. El servidor genera audio más rápido que en tiempo real, por lo que este evento es útil cuando el usuario interrumpe para truncar el audio que se envió al cliente pero que aún no se ha reproducido. La comprensión del servidor del audio con la reproducción del cliente está sincronizada.

El truncamiento de audio elimina la transcripción de texto del lado servidor para asegurarse de que no haya texto en el contexto del que el usuario no conoce.

Si el evento de cliente se ejecuta correctamente, el servidor responde con un evento conversation.item.truncated.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.item.truncate.
item_id string Identificador del elemento de mensaje del asistente que se va a truncar. Solo se pueden truncar los elementos del mensaje del asistente.
content_index integer Índice del elemento de contenido que se va a truncar. Establezca esta propiedad en "0".
audio_end_ms integer Duración inclusiva hasta la que se trunca el audio, en milisegundos. Si el audio_end_ms es mayor que la duración real del audio, el servidor responde con un error.

RealtimeClientEventInputAudioBufferAppend

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser input_audio_buffer.append.
audio string Bytes de audio codificados en Base64. Este valor debe estar en el formato especificado por el campo input_audio_format en la configuración de sesión.

RealtimeClientEventInputAudioBufferClear

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.

Estructura de eventos

{
  "type": "input_audio_buffer.clear"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser input_audio_buffer.clear.

RealtimeClientEventInputAudioBufferCommit

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.

Estructura de eventos

{
  "type": "input_audio_buffer.commit"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser input_audio_buffer.commit.

RealtimeClientEventResponseCancel

El evento de cliente response.cancel se usa para cancelar una respuesta en curso.

El servidor responde con un evento response.cancelled o un error si no hay ninguna respuesta para cancelar.

Estructura de eventos

{
  "type": "response.cancel"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.cancel.

RealtimeClientEventResponseCreate

El evento de cliente response.create se usa para indicar al servidor que cree una respuesta a través de la inferencia del modelo. Cuando la sesión está configurada en modo VAD de servidor, el servidor crea respuestas automáticamente.

Una respuesta incluye al menos un item y puede tener dos, en cuyo caso el segundo es una llamada de función. Estos elementos se anexan al historial de conversaciones.

El servidor responde con un evento response.created, uno o varios eventos de elemento y contenido (como conversation.item.created y response.content_part.added) y, por último, un evento response.done para indicar que la respuesta está completa.

Nota

El evento de cliente response.create incluye la configuración de inferencia como instructions, y temperature. Estos campos pueden invalidar la configuración de la sesión solo para esta respuesta.

Estructura de eventos

{
  "type": "response.create"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.create.
response RealtimeResponseOptions Opciones de respuesta.

RealtimeClientEventSessionUpdate

El evento de cliente session.update se usa para actualizar la configuración predeterminada de la sesión. El cliente puede enviar este evento en cualquier momento para actualizar la configuración de la sesión y cualquier campo se puede actualizar en cualquier momento, excepto la voz.

Solo se actualizan los campos que están presentes. Para borrar un campo (como instructions), pase una cadena vacía.

El servidor responde con un evento session.updated que contiene la configuración efectiva completa.

Estructura de eventos

{
  "type": "session.update"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser session.update.
session RealtimeRequestSession Configuración de la sesión.

Eventos del servidor

Hay 28 eventos de servidor que se pueden recibir del servidor:

Evento Descripción
RealtimeServerEventConversationCreated El evento de servidor conversation.created se devuelve justo después de la creación de la sesión. Se crea una conversación por sesión.
RealtimeServerEventConversationItemCreated El evento de servidor conversation.item.created se devuelve cuando se crea un elemento de conversación.
RealtimeServerEventConversationItemDeleted El evento de servidor conversation.item.deleted se devuelve cuando el cliente eliminó un elemento de la conversación con un evento conversation.item.delete.
RealtimeServerEventConversationItemInputAudioTranscriptionCompleted 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.
RealtimeServerEventConversationItemInputAudioTranscriptionFailed 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.
RealtimeServerEventConversationItemTruncated 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.
RealtimeServerEventError 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.
RealtimeServerEventInputAudioBufferCleared 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.
RealtimeServerEventInputAudioBufferCommitted 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.
RealtimeServerEventInputAudioBufferSpeechStarted 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.
RealtimeServerEventInputAudioBufferSpeechStopped 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.
RealtimeServerEventRateLimitsUpdated El evento de servidor rate_limits.updated se emite al principio de una respuesta para indicar los límites de velocidad actualizados.
RealtimeServerEventResponseAudioDelta El evento de servidor response.audio.delta se devuelve cuando se actualiza el audio generado por el modelo.
RealtimeServerEventResponseAudioDone El evento de servidor response.audio.done se devuelve cuando se realiza el audio generado por el modelo.
RealtimeServerEventResponseAudioTranscriptDelta El evento de servidor response.audio_transcript.delta se devuelve cuando se actualiza la transcripción generada por el modelo de salida de audio.
RealtimeServerEventResponseAudioTranscriptDone 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.
RealtimeServerEventResponseContentPartAdded El evento del servidor response.content_part.added se devuelve cuando se agrega una nueva parte de contenido a un elemento de mensaje del asistente.
RealtimeServerEventResponseContentPartDone El evento de servidor response.content_part.done se devuelve cuando se realiza la transmisión por secuencias de un elemento de contenido.
RealtimeServerEventResponseCreated El evento de servidor response.created se devuelve cuando se crea una nueva respuesta. Este es el primer evento de creación de respuesta, donde la respuesta está en un estado inicial de in_progress.
RealtimeServerEventResponseDone El evento de servidor response.done se devuelve cuando se termina de transmitir una respuesta.
RealtimeServerEventResponseFunctionCallArgumentsDelta 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.
RealtimeServerEventResponseFunctionCallArgumentsDone 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.
RealtimeServerEventResponseOutputItemAdded El evento de servidor response.output_item.added se devuelve cuando se crea un nuevo elemento durante la generación de la respuesta.
RealtimeServerEventResponseOutputItemDone El evento de servidor response.output_item.done se devuelve cuando un elemento ha terminado de transmitirse.
RealtimeServerEventResponseTextDelta El evento de servidor response.text.delta se devuelve cuando se actualiza el texto generado por el modelo.
RealtimeServerEventResponseTextDone El evento de servidor response.text.done se devuelve cuando el texto generado por el modelo ha terminado de transmitirse.
RealtimeServerEventSessionCreated El evento de servidor session.created es el primer evento de servidor cuando se establece una nueva conexión a la API Realtime. Este evento crea y devuelve una nueva sesión con la configuración de sesión predeterminada.
RealtimeServerEventSessionUpdated El cliente devuelve el evento de servidor session.updated cuando el cliente actualiza una sesión. Si se produce un error, el servidor envía un evento error en su lugar.

RealtimeServerEventConversationCreated

El evento de servidor conversation.created se devuelve justo después de la creación de la sesión. Se crea una conversación por sesión.

Estructura de eventos

{
  "type": "conversation.created",
  "conversation": {
    "id": "<id>",
    "object": "<object>"
  }
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.created.
conversación objeto Recurso de conversación.

Propiedades de conversación

Campo Tipo Descripción
id string El id. exclusivo de la conversación.
objeto string El tipo de objeto debe ser realtime.conversation.

RealtimeServerEventConversationItemCreated

El evento de servidor conversation.item.created se devuelve cuando se crea un elemento de conversación. Hay varios escenarios que generan este evento:

  • El servidor genera una respuesta que, si se ejecuta correctamente, genera uno o dos elementos, que es de tipo message (rol assistant) o tipo function_call.
  • El cliente o el servidor (en server_vad modo) confirman el búfer de audio de entrada. El servidor toma el contenido del búfer de audio de entrada y lo agrega a un nuevo elemento de mensaje de usuario.
  • El cliente envió un evento conversation.item.create para agregar un nuevo elemento a la conversación.

Estructura de eventos

{
  "type": "conversation.item.created",
  "previous_item_id": "<previous_item_id>"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.item.created.
previous_item_id string El identificador del elemento anterior en el contexto de conversación permite al cliente comprender el orden de la conversación.
item RealtimeConversationResponseItem Elemento que se creó.

RealtimeServerEventConversationItemDeleted

El evento de servidor conversation.item.deleted se devuelve cuando el cliente eliminó un elemento de la conversación con un evento conversation.item.delete. Este evento se usa para sincronizar la comprensión del servidor del historial de conversaciones con la vista del cliente.

Estructura de eventos

{
  "type": "conversation.item.deleted",
  "item_id": "<item_id>"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.item.deleted.
item_id string Identificador del elemento que se eliminó.

RealtimeServerEventConversationItemInputAudioTranscriptionCompleted

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 independiente de reconocimiento de voz, actualmente siempre 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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.item.input_audio_transcription.completed.
item_id string Identificador del elemento de mensaje de usuario que contiene el audio.
content_index integer Índice de la parte de contenido que contiene el audio.
transcript string Texto transcrito.

RealtimeServerEventConversationItemInputAudioTranscriptionFailed

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.item.input_audio_transcription.failed.
item_id string Identificador del elemento de mensaje de usuario.
content_index integer Índice de la parte de contenido que contiene el audio.
error objeto Detalles del error de transcripción.

Consulte las propiedades anidadas en la tabla siguiente.

Propiedades de errores

Campo Tipo Descripción
type cadena Tipo de error.
code string Código de error, si existe.
message string Mensaje de error legible.
param string Parámetro relacionado con el error, si existe.

RealtimeServerEventConversationItemTruncated

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser conversation.item.truncated.
item_id string Identificador del elemento de mensaje del asistente que se ha truncado.
content_index integer Índice de la parte de contenido truncada.
audio_end_ms integer Duración hasta la que se truncó el audio, en milisegundos.

RealtimeServerEventError

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser error.
error objeto Detalles del error.

Consulte las propiedades anidadas en la tabla siguiente.

Propiedades de errores

Campo Tipo Descripción
type cadena Tipo de error. Por ejemplo, "invalid_request_error" y "server_error" son tipos de error.
code string Código de error, si existe.
message string Mensaje de error legible.
param string Parámetro relacionado con el error, si existe.
event_id string Identificador del evento de cliente que provocó el error, si procede.

RealtimeServerEventInputAudioBufferCleared

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.

Estructura de eventos

{
  "type": "input_audio_buffer.cleared"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser input_audio_buffer.cleared.

RealtimeServerEventInputAudioBufferCommitted

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser input_audio_buffer.committed.
previous_item_id string Identificador del elemento anterior después del cual se inserta el nuevo elemento.
item_id string Identificador del elemento de mensaje de usuario creado.

RealtimeServerEventInputAudioBufferSpeechStarted

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).

Nota

El cliente puede querer usar este evento para interrumpir la reproducción de audio o proporcionar comentarios visuales al usuario.

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser input_audio_buffer.speech_started.
audio_start_ms integer Milisegundos desde el principio de todo el audio escrito en el búfer durante la sesión cuando se detectó la voz por primera vez. Esta propiedad corresponde al principio del audio enviado al modelo y, por tanto, incluye el prefix_padding_ms configurado en la sesión.
item_id string Identificador del elemento de mensaje de usuario creado cuando se detiene la voz.

RealtimeServerEventInputAudioBufferSpeechStopped

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser input_audio_buffer.speech_stopped.
audio_end_ms integer Milisegundos desde que se inició la sesión cuando se detuvo la voz. Esta propiedad corresponde al final del audio enviado al modelo y por tanto, incluye el min_silence_duration_ms configurado en la sesión.
item_id string Identificador del elemento de mensaje de usuario creado.

RealtimeServerEventRateLimitsUpdated

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser rate_limits.updated.
rate_limits matriz de RealtimeServerEventRateLimitsUpdatedRateLimitsItem Lista de información de límite de velocidad.

RealtimeServerEventResponseAudioDelta

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

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.audio.delta.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento.
output_index integer Índice del elemento de salida en la respuesta.
content_index integer Índice de la parte de contenido de la matriz de contenido del elemento.
delta string Delta de datos de audio codificados en Base64.

RealtimeServerEventResponseAudioDone

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.audio.done.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento.
output_index integer Índice del elemento de salida en la respuesta.
content_index integer Índice de la parte de contenido de la matriz de contenido del elemento.

RealtimeServerEventResponseAudioTranscriptDelta

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

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.audio_transcript.delta.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento.
output_index integer Índice del elemento de salida en la respuesta.
content_index integer Índice de la parte de contenido de la matriz de contenido del elemento.
delta string Delta de transcripción.

RealtimeServerEventResponseAudioTranscriptDone

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.audio_transcript.done.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento.
output_index integer Índice del elemento de salida en la respuesta.
content_index integer Índice de la parte de contenido de la matriz de contenido del elemento.
transcript string Transcripción final del audio.

RealtimeServerEventResponseContentPartAdded

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.

Estructura de eventos

{
  "type": "response.content_part.added",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.content_part.added.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento al que se agregó la parte de contenido.
output_index integer Índice del elemento de salida en la respuesta.
content_index integer Índice de la parte de contenido de la matriz de contenido del elemento.
parte RealtimeContentPart Elemento de contenido que se agregó.

Propiedades de partes

Campo Tipo Descripción
type RealtimeContentPartType

RealtimeServerEventResponseContentPartDone

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.content_part.done.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento.
output_index integer Índice del elemento de salida en la respuesta.
content_index integer Índice de la parte de contenido de la matriz de contenido del elemento.
parte RealtimeContentPart Elemento de contenido que se realiza.

Propiedades de partes

Campo Tipo Descripción
type RealtimeContentPartType

RealtimeServerEventResponseCreated

El evento de servidor response.created se devuelve cuando se crea una nueva respuesta. Este es el primer evento de creación de respuesta, donde la respuesta está en un estado inicial de in_progress.

Estructura de eventos

{
  "type": "response.created"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.created.
response RealtimeResponse Objeto de respuesta.

RealtimeServerEventResponseDone

El evento de servidor response.done se devuelve cuando se termina de transmitir una respuesta. Este evento siempre se emite, independientemente del estado final. El objeto de respuesta incluido en el evento response.done incluye todos los elementos de salida de la respuesta, pero omite los datos de audio sin procesar.

Estructura de eventos

{
  "type": "response.done"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.done.
response RealtimeResponse Objeto de respuesta.

RealtimeServerEventResponseFunctionCallArgumentsDelta

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.function_call_arguments.delta.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento de llamada de función.
output_index integer Índice del elemento de salida en la respuesta.
call_id string Identificador de la llamada de función.
delta string Los argumentos delta como una cadena JSON.

RealtimeServerEventResponseFunctionCallArgumentsDone

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.function_call_arguments.done.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento de llamada de función.
output_index integer Índice del elemento de salida en la respuesta.
call_id string Identificador de la llamada de función.
argumentos string Argumentos finales como una cadena JSON.

RealtimeServerEventResponseOutputItemAdded

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

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.output_item.added.
response_id string Identificador de la respuesta a la que pertenece el elemento.
output_index integer Índice del elemento de salida en la respuesta.
item RealtimeConversationResponseItem Elemento que se agregó.

RealtimeServerEventResponseOutputItemDone

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.output_item.done.
response_id string Identificador de la respuesta a la que pertenece el elemento.
output_index integer Índice del elemento de salida en la respuesta.
item RealtimeConversationResponseItem Elemento que ha terminado de transmitirse.

RealtimeServerEventResponseTextDelta

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.text.delta.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento.
output_index integer Índice del elemento de salida en la respuesta.
content_index integer Índice de la parte de contenido de la matriz de contenido del elemento.
delta string Delta de texto.

RealtimeServerEventResponseTextDone

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.

Estructura de eventos

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

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser response.text.done.
response_id string Identificador de la respuesta.
item_id string Identificador del elemento.
output_index integer Índice del elemento de salida en la respuesta.
content_index integer Índice de la parte de contenido de la matriz de contenido del elemento.
text string El contenido final del texto.

RealtimeServerEventSessionCreated

El evento de servidor session.created es el primer evento de servidor cuando se establece una nueva conexión a la API Realtime. Este evento crea y devuelve una nueva sesión con la configuración de sesión predeterminada.

Estructura de eventos

{
  "type": "session.created"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser session.created.
session RealtimeResponseSession Objeto de sesión.

RealtimeServerEventSessionUpdated

El cliente devuelve el evento de servidor session.updated cuando el cliente actualiza una sesión. Si se produce un error, el servidor envía un evento error en su lugar.

Estructura de eventos

{
  "type": "session.updated"
}

Propiedades

Campo Tipo Descripción
type cadena El tipo de evento debe ser session.updated.
session RealtimeResponseSession Objeto de sesión.

Componentes

RealtimeAudioFormat

Valores permitidos:

  • pcm16
  • g711_ulaw
  • g711_alaw

RealtimeAudioInputTranscriptionModel

Valores permitidos:

  • whisper-1

RealtimeAudioInputTranscriptionSettings

Campo Tipo Descripción
model RealtimeAudioInputTranscriptionModel El modelo predeterminado whisper-1 es actualmente el único modelo admitido para la transcripción de entrada de audio.

RealtimeClientEvent

Campo Tipo Descripción
type RealtimeClientEventType Tipo del evento de cliente.
event_id string Id. exclusivo del evento. El cliente puede especificar el identificador para ayudar a identificar el evento.

RealtimeClientEventType

Valores permitidos:

  • session.update
  • input_audio_buffer.append
  • input_audio_buffer.commit
  • input_audio_buffer.clear
  • conversation.item.create
  • conversation.item.delete
  • conversation.item.truncate
  • response.create
  • response.cancel

RealtimeContentPart

Campo Tipo Descripción
type RealtimeContentPartType El tipo de contenido.

Propiedad del objeto function.

Valores permitidos: input_text, input_audio, item_reference, text.
text string Contenido de texto. Esta propiedad es aplicable a los tipos de contenido input_text y text.
id string Identificador de un elemento de conversación anterior al que se va a hacer referencia tanto en elementos creados por el cliente como en el servidor. Esta propiedad es aplicable al tipo de contenido item_reference en eventos response.create.
audio string Bytes de audio codificados en base64. Esta propiedad es aplicable al tipo de contenido input_audio.
transcript string Transcripción del audio. Esta propiedad es aplicable al tipo de contenido input_audio.

RealtimeContentPartType

Valores permitidos:

  • input_text
  • input_audio
  • text
  • audio

RealtimeConversationItemBase

Elemento que se va a agregar a la conversación.

En esta tabla se describen todas las propiedades de RealtimeConversationItem. Las propiedades aplicables por evento dependen del RealtimeItemType.

Campo Tipo Descripción
id string Id. exclusivo del elemento. El cliente puede especificar el identificador para ayudar a administrar el contexto del lado servidor. Si el cliente no proporciona un identificador, el servidor genera uno.
type RealtimeItemType Tipo del elemento.

Valores permitidos: message, function_call y function_call_output
objeto string Identificador del objeto de API que se devuelve. El valor siempre será realtime.item.
status RealtimeItemStatus Estado del elemento. Este campo no afecta a la conversación, pero se acepta para la coherencia con el evento conversation.item.created.

Valores permitidos: completed, incomplete
rol RealtimeMessageRole Rol del remitente del mensaje. Esta propiedad solo es aplicable a message elementos.

Valores permitidos: system, user y assistant
content matriz de RealtimeContentPart Contenido del mensaje. Esta propiedad solo es aplicable a message elementos.

- Los elementos de mensaje del rol system solo admiten contenido input_text.
- Los elementos de mensaje del rol user admiten input_text y contenido de input_audio.
- Los elementos de mensaje del rol assistant admiten contenido text.
call_id string Identificador de la llamada de función (para elementos function_call y function_call_output). Si se pasa en un elemento de function_call_output, el servidor comprobará que existe un elemento function_call con el mismo identificador en el historial de conversaciones.
nombre string Nombre de la función a la que se llama (para function_call elementos).
argumentos string Argumentos de la llamada de función (para function_call elementos).
output string Salida de la llamada de función (para function_call_output elementos).

RealtimeConversationRequestItem

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

Campo Tipo Descripción
type RealtimeItemType Tipo del elemento.
id string Id. exclusivo del elemento. El cliente puede especificar el identificador para ayudar a administrar el contexto del lado servidor. Si el cliente no proporciona un identificador, el servidor genera uno.

RealtimeConversationResponseItem

El objeto RealtimeConversationResponseItem representa un elemento de la conversación. Se usa en algunos de los eventos de servidor, como:

Campo Tipo Description
object string Identificador del objeto de API devuelto.

Valores permitidos: realtime.item
type RealtimeItemType Tipo del elemento.

Valores permitidos: message, function_call y function_call_output
id string Id. exclusivo del elemento. El cliente puede especificar el identificador para ayudar a administrar el contexto del lado servidor. Si el cliente no proporciona un identificador, el servidor genera uno.

Esta propiedad admite valores NULL.

RealtimeFunctionTool

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

Campo Tipo Descripción
type cadena El tipo de la herramienta.

Valores permitidos: function
nombre string El nombre de la función.
descripción string Descripción de la función, incluidas las directrices de uso. Por ejemplo, "Use esta función para obtener la hora actual".
parámetros objeto Parámetros de la función en forma de un objeto JSON.

RealtimeItemStatus

Valores permitidos:

  • in_progress
  • completed
  • incomplete

RealtimeItemType

Valores permitidos:

  • message
  • function_call
  • function_call_output

RealtimeMessageRole

Valores permitidos:

  • system
  • user
  • assistant

RealtimeRequestAssistantMessageItem

Campo Tipo Descripción
rol string Rol del mensaje.

Valores permitidos: assistant
content matriz de RealtimeRequestTextContentPart Contenido del mensaje.

RealtimeRequestAudioContentPart

Campo Tipo Descripción
type cadena Tipo del elemento de contenido.

Valores permitidos: input_audio
transcript string Transcripción del audio.

RealtimeRequestFunctionCallItem

Campo Tipo Descripción
type cadena Tipo del elemento.

Valores permitidos: function_call
nombre string Nombre del elemento de llamada de función.
call_id string Identificador del elemento de llamada de función.
argumentos string Argumentos del elemento de llamada de función.
status RealtimeItemStatus Estado del elemento.

RealtimeRequestFunctionCallOutputItem

Campo Tipo Descripción
type cadena Tipo del elemento.

Valores permitidos: function_call_output
call_id string Identificador del elemento de llamada de función.
output string Salida del elemento de llamada de función.

RealtimeRequestMessageItem

Campo Tipo Descripción
type cadena Tipo del elemento.

Valores permitidos: message
rol RealtimeMessageRole Rol del mensaje.
status RealtimeItemStatus Estado del elemento.

RealtimeRequestMessageReferenceItem

Campo Tipo Descripción
type cadena Tipo del elemento.

Valores permitidos: message
id string Identificador del elemento de mensaje.

RealtimeRequestSession

El objeto RealtimeRequestSession se usa cuando desea actualizar la configuración de sesión a través del evento session.update.

Campo Tipo Descripción
modalidades array Las modalidades que admite la sesión.

Valores permitidos: text, audio

Por ejemplo, "modalities": ["text", "audio"] es la configuración predeterminada que habilita las modalidades de texto y audio. Para habilitar solo texto, establezca "modalities": ["text"]. No se puede habilitar solo el audio.
detalladas string Las instrucciones (el mensaje del sistema) para guiar las respuestas de texto y audio del modelo.

Estas son algunas instrucciones de ejemplo para ayudar a guiar el contenido y el formato de las respuestas de texto y audio:
"instructions": "be succinct"
"instructions": "act friendly"
"instructions": "here are examples of good responses"

Estas son algunas instrucciones de ejemplo para ayudar a guiar el comportamiento del audio:
"instructions": "talk quickly"
"instructions": "inject emotion into your voice"
"instructions": "laugh frequently"

Aunque es posible que el modelo no siga siempre estas instrucciones, proporcionan instrucciones sobre el comportamiento deseado.
voice RealtimeVoice Voz usada para la respuesta del modelo para la sesión.

Una vez que la voz se usa en la sesión para la respuesta de audio del modelo, no se puede cambiar.
input_audio_format RealtimeAudioFormat Formato del audio de entrada.
output_audio_format RealtimeAudioFormat Formato del audio de salida.
input_audio_transcription RealtimeAudioInputTranscriptionSettings La configuración de la transcripción de entrada de audio.

Esta propiedad admite valores NULL.
turn_detection RealtimeTurnDetection Configuración de detección de turno para la sesión.

Esta propiedad admite valores NULL.
manuales matriz de RealtimeTool Las herramientas disponibles para el modelo para la sesión.
tool_choice RealtimeToolChoice La opción de herramienta para la sesión.

Valores permitidos: auto, none y required. De lo contrario, puede especificar el nombre de la función que se va a usar.
temperatura number Temperatura de muestreo del modelo. Los valores de temperatura permitidos están limitados a [0.6, 1.2]. El valor predeterminado es 0.8.
max_response_output_tokens entero o "inf" El número máximo de tokens de salida por respuesta del asistente, incluido el de las llamadas a herramientas.

Especifique un entero entre 1 y 4096 para limitar los tokens de salida. De lo contrario, establezca el valor en "inf" para permitir el número máximo de tokens.

Por ejemplo, para limitar los tokens de salida a 1000, establezca "max_response_output_tokens": 1000. Para permitir el número máximo de tokens, establezca "max_response_output_tokens": "inf".

Tiene como valor predeterminado "inf".

RealtimeRequestSystemMessageItem

Campo Tipo Descripción
rol string Rol del mensaje.

Valores permitidos: system
content matriz de RealtimeRequestTextContentPart Contenido del mensaje.

RealtimeRequestTextContentPart

Campo Tipo Descripción
type cadena Tipo del elemento de contenido.

Valores permitidos: input_text
text string Contenido de texto.

RealtimeRequestUserMessageItem

Campo Tipo Descripción
rol string Rol del mensaje.

Valores permitidos: user
content matriz de RealtimeRequestTextContentPart o RealtimeRequestAudioContentPart Contenido del mensaje.

RealtimeResponse

Campo Tipo Description
object string Objeto de respuesta.

Valores permitidos: realtime.response
id string Id. exclusivo de la respuesta.
status RealtimeResponseStatus Estado de la respuesta.

El valor del estado predeterminado es in_progress.
status_details RealtimeResponseStatusDetails Detalles del estado de la respuesta.

Esta propiedad admite valores NULL.
output matriz de RealtimeConversationResponseItem Elementos de salida de la respuesta.
usada objeto Estadísticas de uso de la respuesta. Cada sesión de la API Realtime mantiene un contexto de conversación y anexa nuevos elementos a la conversación. La salida de turnos anteriores (tokens de texto y audio) es la entrada para turnos posteriores.

Consulte las propiedades anidadas a continuación.
+ total_tokens integer Número total de tokens en la respuesta, incluidos los tokens de texto de entrada y salida y audio.

Propiedad del objeto usage.
+ input_tokens integer Número de tokens de entrada usados en la respuesta, incluidos los tokens de texto y audio.

Propiedad del objeto usage.
+ output_tokens integer Número de tokens de salida enviados en la respuesta, incluidos los tokens de texto y audio.

Propiedad del objeto usage.
+ input_token_details objeto Detalles sobre los tokens de entrada usados en la respuesta.

Propiedad del objeto usage.
br>
Consulte las propiedades anidadas a continuación.
+ cached_tokens integer Número de tokens almacenados en caché que se usan en la respuesta.

Propiedad del objeto input_token_details.
+ text_tokens integer Número de tokens de texto usados en la respuesta.

Propiedad del objeto input_token_details.
+ audio_tokens integer Número de tokens de audio usados en la respuesta.

Propiedad del objeto input_token_details.
+ output_token_details objeto Detalles sobre los tokens de salida usados en la respuesta.

Propiedad del objeto usage.

Consulte las propiedades anidadas a continuación.
+ text_tokens integer Número de tokens de texto usados en la respuesta.

Propiedad del objeto output_token_details.
+ audio_tokens integer Número de tokens de audio usados en la respuesta.

Propiedad del objeto output_token_details.

RealtimeResponseAudioContentPart

Campo Tipo Descripción
type cadena Tipo del elemento de contenido.

Valores permitidos: audio
transcript string Transcripción del audio.

Esta propiedad admite valores NULL.

RealtimeResponseBase

Recurso de respuesta.

RealtimeResponseFunctionCallItem

Campo Tipo Descripción
type cadena Tipo del elemento.

Valores permitidos: function_call
nombre string Nombre del elemento de llamada de función.
call_id string Identificador del elemento de llamada de función.
argumentos string Argumentos del elemento de llamada de función.
status RealtimeItemStatus Estado del elemento.

RealtimeResponseFunctionCallOutputItem

Campo Tipo Descripción
type cadena Tipo del elemento.

Valores permitidos: function_call_output
call_id string Identificador del elemento de llamada de función.
output string Salida del elemento de llamada de función.

RealtimeResponseMessageItem

Campo Tipo Descripción
type cadena Tipo del elemento.

Valores permitidos: message
rol RealtimeMessageRole Rol del mensaje.
content array Contenido del mensaje.

Elementos de matriz: RealtimeResponseTextContentPart
status RealtimeItemStatus Estado del elemento.

RealtimeResponseOptions

Campo Tipo Descripción
modalidades array Las modalidades que admite la sesión.

Valores permitidos: text, audio

Por ejemplo, "modalities": ["text", "audio"] es la configuración predeterminada que habilita las modalidades de texto y audio. Para habilitar solo texto, establezca "modalities": ["text"]. No se puede habilitar solo el audio.
detalladas string Las instrucciones (el mensaje del sistema) para guiar las respuestas de texto y audio del modelo.

Estas son algunas instrucciones de ejemplo para ayudar a guiar el contenido y el formato de las respuestas de texto y audio:
"instructions": "be succinct"
"instructions": "act friendly"
"instructions": "here are examples of good responses"

Estas son algunas instrucciones de ejemplo para ayudar a guiar el comportamiento del audio:
"instructions": "talk quickly"
"instructions": "inject emotion into your voice"
"instructions": "laugh frequently"

Aunque es posible que el modelo no siga siempre estas instrucciones, proporcionan instrucciones sobre el comportamiento deseado.
voice RealtimeVoice Voz usada para la respuesta del modelo para la sesión.

Una vez que la voz se usa en la sesión para la respuesta de audio del modelo, no se puede cambiar.
output_audio_format RealtimeAudioFormat Formato del audio de salida.
manuales matriz de RealtimeTool Las herramientas disponibles para el modelo para la sesión.
tool_choice RealtimeToolChoice La opción de herramienta para la sesión.
temperatura number Temperatura de muestreo del modelo. Los valores de temperatura permitidos están limitados a [0.6, 1.2]. El valor predeterminado es 0.8.
max__output_tokens entero o "inf" El número máximo de tokens de salida por respuesta del asistente, incluido el de las llamadas a herramientas.

Especifique un entero entre 1 y 4096 para limitar los tokens de salida. De lo contrario, establezca el valor en "inf" para permitir el número máximo de tokens.

Por ejemplo, para limitar los tokens de salida a 1000, establezca "max_response_output_tokens": 1000. Para permitir el número máximo de tokens, establezca "max_response_output_tokens": "inf".

Tiene como valor predeterminado "inf".
conversación string Controla a qué conversación se agrega la respuesta. Los valores admitidos son auto y none.

El valor de auto (o no establecer esta propiedad) garantiza que el contenido de la respuesta se agregue a la conversación predeterminada de la sesión.

Establezca esta propiedad en none para crear una respuesta fuera de banda donde los elementos no se agregarán a la conversación predeterminada. Para obtener más información, consulte la guía paso a paso.

De manera predeterminada, su valor es "auto".
metadata map Configuración de hasta 16 pares clave-valor que se pueden asociar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado. Las claves pueden tener un máximo de 64 caracteres y los valores pueden tener un máximo de 512 caracteres.

Por ejemplo: metadata: { topic: "classification" }
input array Elementos de entrada que se van a incluir en la solicitud del modelo. Crea un nuevo contexto para esta respuesta, sin incluir la conversación predeterminada. Puede incluir referencias a elementos de la conversación predeterminada.

Elementos de matriz: RealtimeConversationItemBase

RealtimeResponseSession

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

Campo Tipo Description
object string Objeto de sesión.

Valores permitidos: realtime.session
id string Id. exclusivo de la sesión.
model string Modelo usado para la sesión.
modalidades array Las modalidades que admite la sesión.

Valores permitidos: text, audio

Por ejemplo, "modalities": ["text", "audio"] es la configuración predeterminada que habilita las modalidades de texto y audio. Para habilitar solo texto, establezca "modalities": ["text"]. No se puede habilitar solo el audio.
detalladas string Las instrucciones (el mensaje del sistema) para guiar las respuestas de texto y audio del modelo.

Estas son algunas instrucciones de ejemplo para ayudar a guiar el contenido y el formato de las respuestas de texto y audio:
"instructions": "be succinct"
"instructions": "act friendly"
"instructions": "here are examples of good responses"

Estas son algunas instrucciones de ejemplo para ayudar a guiar el comportamiento del audio:
"instructions": "talk quickly"
"instructions": "inject emotion into your voice"
"instructions": "laugh frequently"

Aunque es posible que el modelo no siga siempre estas instrucciones, proporcionan instrucciones sobre el comportamiento deseado.
voice RealtimeVoice Voz usada para la respuesta del modelo para la sesión.

Una vez que la voz se usa en la sesión para la respuesta de audio del modelo, no se puede cambiar.
input_audio_format RealtimeAudioFormat Formato del audio de entrada.
output_audio_format RealtimeAudioFormat Formato del audio de salida.
input_audio_transcription RealtimeAudioInputTranscriptionSettings La configuración de la transcripción de entrada de audio.

Esta propiedad admite valores NULL.
turn_detection RealtimeTurnDetection Configuración de detección de turno para la sesión.

Esta propiedad admite valores NULL.
manuales matriz de RealtimeTool Las herramientas disponibles para el modelo para la sesión.
tool_choice RealtimeToolChoice La opción de herramienta para la sesión.
temperatura number Temperatura de muestreo del modelo. Los valores de temperatura permitidos están limitados a [0.6, 1.2]. El valor predeterminado es 0.8.
max_response_output_tokens entero o "inf" El número máximo de tokens de salida por respuesta del asistente, incluido el de las llamadas a herramientas.

Especifique un entero entre 1 y 4096 para limitar los tokens de salida. De lo contrario, establezca el valor en "inf" para permitir el número máximo de tokens.

Por ejemplo, para limitar los tokens de salida a 1000, establezca "max_response_output_tokens": 1000. Para permitir el número máximo de tokens, establezca "max_response_output_tokens": "inf".

RealtimeResponseStatus

Valores permitidos:

  • in_progress
  • completed
  • cancelled
  • incomplete
  • failed

RealtimeResponseStatusDetails

Campo Tipo Descripción
type RealtimeResponseStatus Estado de la respuesta.

RealtimeResponseTextContentPart

Campo Tipo Descripción
type cadena Tipo del elemento de contenido.

Valores permitidos: text
text string Contenido de texto.

RealtimeServerEvent

Campo Tipo Descripción
type RealtimeServerEventType Tipo del evento de servidor.
event_id string Identificador único del evento de servidor.

RealtimeServerEventRateLimitsUpdatedRateLimitsItem

Campo Tipo Descripción
name string El nombre de la propiedad de límite de velocidad sobre el que este elemento incluye información.
limit integer Límite máximo configurado para esta propiedad de límite de velocidad.
restante integer Cuota restante disponible con respecto al límite configurado para esta propiedad de límite de velocidad.
reset_seconds number El tiempo restante, en segundos, hasta que se restablezca esta propiedad de límite de velocidad.

RealtimeServerEventType

Valores permitidos:

  • session.created
  • session.updated
  • conversation.created
  • conversation.item.created
  • conversation.item.deleted
  • conversation.item.truncated
  • response.created
  • response.done
  • rate_limits.updated
  • response.output_item.added
  • response.output_item.done
  • response.content_part.added
  • response.content_part.done
  • response.audio.delta
  • response.audio.done
  • response.audio_transcript.delta
  • response.audio_transcript.done
  • response.text.delta
  • response.text.done
  • response.function_call_arguments.delta
  • response.function_call_arguments.done
  • input_audio_buffer.speech_started
  • input_audio_buffer.speech_stopped
  • conversation.item.input_audio_transcription.completed
  • conversation.item.input_audio_transcription.failed
  • input_audio_buffer.committed
  • input_audio_buffer.cleared
  • error

RealtimeServerVadTurnDetection

Campo Tipo Descripción
type cadena Tipo de detección de turno.

Valores permitidos: server_vad
threshold number Umbral de activación para la detección de turno de VAD del servidor. En entornos ruidosos, es posible que tenga que aumentar el umbral para evitar falsos positivos. En entornos silenciosos, es posible que tenga que reducir el umbral para evitar falsos negativos.

Tiene como valor predeterminado 0.5. Puede establecer el umbral en un valor entre 0.0 y 1.0.
prefix_padding_ms string Duración del audio de voz (en milisegundos) a incluir antes del inicio de la voz detectada.

Tiene como valor predeterminado 300.
silence_duration_ms string Duración del silencio (en milisegundos) para detectar el final de la voz. Quiere detectar el final de la voz lo antes posible, pero no demasiado pronto para evitar cortar la última parte de la voz.

El modelo responderá más rápidamente si ajusta este valor a un número más bajo, pero podría cortar la última parte de la voz. Si ajusta este valor a un número más alto, el modelo esperará más tiempo para detectar el final de la voz, pero podría tardar más en responder.

RealtimeSessionBase

Configuración del objeto de sesión en tiempo real.

RealtimeTool

Representación base de una definición de herramienta en tiempo real.

Campo Tipo Descripción
type RealtimeToolType El tipo de la herramienta.

RealtimeToolChoice

Conjunto combinado de representaciones disponibles para un parámetro de tool_choice en tiempo real, que abarca ambas opciones literales de cadena, como "auto" y referencias estructuradas a herramientas definidas.

RealtimeToolChoiceFunctionObject

Representación de un tool_choice en tiempo real seleccionando una herramienta de función con nombre.

Campo Tipo Descripción
type cadena Tipo de la propiedad tool_choice.

Valores permitidos: function
function objeto Herramienta de función a seleccionar.

Consulte las propiedades anidadas a continuación.
+ nombre string Nombre de la herramienta de función.

Propiedad del objeto function.

RealtimeToolChoiceLiteral

Conjunto disponible de opciones de literal de cadena de nivel de modo tool_choice para el punto de conexión en tiempo real.

Valores permitidos:

  • auto
  • none
  • required

RealtimeToolChoiceObject

Representación base de un tool_choice en tiempo real seleccionando una herramienta con nombre.

Campo Tipo Descripción
type RealtimeToolType Tipo de la propiedad tool_choice.

RealtimeToolType

Los discriminadores de tipo de herramienta admitidos para las herramientas en tiempo real. Actualmente, solo se admiten las herramientas "function".

Valores permitidos:

  • function

RealtimeTurnDetection

Campo Tipo Descripción
type RealtimeTurnDetectionType Tipo de detección de turno.

Valores permitidos: server_vad
threshold number Umbral de activación para la detección de turno de VAD del servidor. En entornos ruidosos, es posible que tenga que aumentar el umbral para evitar falsos positivos. En entornos silenciosos, es posible que tenga que reducir el umbral para evitar falsos negativos.

Tiene como valor predeterminado 0.5. Puede establecer el umbral en un valor entre 0.0 y 1.0.
prefix_padding_ms string Duración del audio de voz (en milisegundos) a incluir antes del inicio de la voz detectada.

El valor predeterminado es 300 milisegundos.
silence_duration_ms string Duración del silencio (en milisegundos) para detectar el final de la voz. Quiere detectar el final de la voz lo antes posible, pero no demasiado pronto para evitar cortar la última parte de la voz.

El modelo responderá más rápidamente si ajusta este valor a un número más bajo, pero podría cortar la última parte de la voz. Si ajusta este valor a un número más alto, el modelo esperará más tiempo para detectar el final de la voz, pero podría tardar más en responder.

El valor predeterminado es 500 milisegundos.
create_response boolean Indica si el servidor creará automáticamente una respuesta cuando VAD esté habilitado y se detenga la voz.

Tiene como valor predeterminado true.

RealtimeTurnDetectionType

Valores permitidos:

  • server_vad

RealtimeVoice

Valores permitidos:

  • alloy
  • ash
  • ballad
  • coral
  • echo
  • sage
  • shimmer
  • verse