Referencia de eventos de audio

Los eventos en tiempo real se usan para comunicarse entre el cliente y el servidor en aplicaciones de audio en tiempo real. Los eventos se envían como objetos JSON a través de varios puntos de conexión, como WebSockets o WebRTC. Los eventos se usan para administrar la conversación, los búferes de audio y las respuestas en tiempo real.

Puede usar eventos de servidor y cliente de audio con estas API:

A menos que se especifique lo contrario, los eventos descritos en este documento son aplicables a ambas API.

Client events

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

Event Description
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 llamadas de función.
RealtimeClientEventConversationItemDelete El evento de cliente conversation.item.delete se usa para quitar un elemento del historial de conversaciones.
RealtimeClientEventConversationItemRetrieve El evento de cliente conversation.item.retrieve se usa para recuperar 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.
RealtimeClientEventOutputAudioBufferClear El evento de cliente output_audio_buffer.clear se usa para borrar los bytes de audio en el búfer de salida.

Este evento solo es aplicable a WebRTC.
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 llamadas 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 conversation.item.created evento; de lo contrario, se envía un error evento.

Event structure

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

Properties

Field Type Description
type string 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 conversation.item.deleted evento, a menos que el elemento no exista en el historial de conversaciones, en cuyo caso el servidor responde con un error.

Event structure

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

Properties

Field Type Description
type string El tipo de evento debe ser conversation.item.delete.
item_id string Identificador del elemento que se va a eliminar.

RealtimeClientEventConversationItemRetrieve

El evento de cliente conversation.item.retrieve se usa para recuperar la representación del servidor de un elemento específico en el historial de conversaciones. Este evento es útil, por ejemplo, para inspeccionar el audio del usuario después de la cancelación de ruido y VAD.

Si el evento de cliente se realiza correctamente, el servidor responde con un conversation.item.retrieved evento. Si el elemento no existe en el historial de conversaciones, el servidor responderá con un error.

Event structure

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

Properties

Field Type Description
type string El tipo de evento debe ser conversation.item.retrieve.
item_id string Identificador del elemento que se va a recuperar.
event_id string Identificador del evento.

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 realiza correctamente, el servidor responde con un conversation.item.truncated evento.

Event structure

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

Properties

Field Type Description
type string 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, el streaming de 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

Field Type Description
type string 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 input_audio_format campo 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 input_audio_buffer.cleared evento .

Event structure

{
  "type": "input_audio_buffer.clear"
}

Properties

Field Type Description
type string 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 input_audio_buffer.committed evento .

Event structure

{
  "type": "input_audio_buffer.commit"
}

Properties

Field Type Description
type string El tipo de evento debe ser input_audio_buffer.commit.

RealtimeClientEventOutputAudioBufferClear

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

Note

Este evento solo es aplicable a WebRTC.

Este evento debe ir precedido por un response.cancel evento de cliente para detener la generación de la respuesta actual.

El servidor deja de generar audio y responde con un output_audio_buffer.cleared evento.

Event structure

{
  "type": "output_audio_buffer.clear"
}

Properties

Field Type Description
event_id string Identificador del evento que provocó el error.
type string El tipo de evento debe ser output_audio_buffer.clear.

RealtimeClientEventResponseCancel

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

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

Event structure

{
  "type": "response.cancel"
}

Properties

Field Type Description
type string 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 itemy 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 response.created evento, uno o varios eventos de contenido y elementos (como conversation.item.created y response.content_part.added) y, por último, un response.done evento para indicar que la respuesta está completa.

Note

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

Event structure

{
  "type": "response.create"
}

Properties

Field Type Description
type string El tipo de evento debe ser response.create.
response RealtimeResponseOptions Las 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 session.updated evento que contiene la configuración efectiva completa.

Event structure

{
  "type": "session.update"
}

Properties

Field Type Description
type string El tipo de evento debe ser session.update.
session RealtimeRequestSession Configuración de la sesión.

Server events

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

Event Description
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.
RealtimeServerEventConversationItemRetrieved El evento de servidor conversation.item.retrieved se devuelve cuando se recupera 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 conversation.item.delete evento.
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 conversation.item.truncate evento .
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 input_audio_buffer.clear evento.
RealtimeServerEventInputAudioBufferCommitted El evento de servidor input_audio_buffer.committed se devuelve cuando el cliente confirma un búfer de audio de entrada o automáticamente en modo VAD del servidor.
RealtimeServerEventInputAudioBufferSpeechStarted El evento de servidor input_audio_buffer.speech_started se devuelve en server_vad modo cuando se detecta voz en el búfer de audio.
RealtimeServerEventInputAudioBufferSpeechStopped El evento de servidor input_audio_buffer.speech_stopped se devuelve en server_vad modo cuando el servidor detecta el final de la voz en el búfer de audio.
RealtimeServerEventOutputAudioBufferCleared El evento de servidor output_audio_buffer.cleared se devuelve cuando el usuario ha interrumpido (input_audio_buffer.speech_started) o cuando el cliente ha emitido el output_audio_buffer.clear evento para cortar manualmente la respuesta de audio actual.

Este evento solo es aplicable a WebRTC.
RealtimeServerEventOutputAudioBufferStarted El evento de servidor output_audio_buffer.started se devuelve cuando el servidor comienza a transmitir audio al cliente. Este evento se genera después de agregar una parte de contenido de audio (response.content_part.added) a la respuesta.

Este evento solo es aplicable a WebRTC.
RealtimeServerEventOutputAudioBufferStopped El evento de servidor output_audio_buffer.stopped se devuelve cuando el búfer de audio de salida se ha purgado completamente en el servidor y no hay más audio disponible.

Este evento solo es aplicable a WebRTC.
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 se realiza en streaming.
RealtimeServerEventResponseContentPartAdded El evento de servidor response.content_part.added se devuelve cuando se agrega una nueva parte de contenido a un elemento de mensaje auxiliar.
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 realiza la transmisión por secuencias de 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 llamada de función generados por el modelo se realizan streaming.
RealtimeServerEventResponseOutputItemAdded El evento de servidor response.output_item.added se devuelve cuando se crea un nuevo elemento durante la generación de respuestas.
RealtimeServerEventResponseOutputItemDone El evento de servidor response.output_item.done se devuelve cuando se realiza la transmisión por secuencias de un elemento.
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 se realiza streaming.
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 error evento 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.

Event structure

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

Properties

Field Type Description
type string El tipo de evento debe ser conversation.created.
conversation object Recurso de conversación.

Conversation properties

Field Type Description
id string Identificador único de la conversación.
object 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 conversation.item.create evento para agregar un nuevo elemento a la conversación.

Event structure

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

Properties

Field Type Description
type string 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ó.

RealtimeServerEventConversationItemRetrieved

El evento de servidor conversation.item.retrieved se devuelve cuando se recupera un elemento de conversación.

Event structure

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

Properties

Field Type Description
type string El tipo de evento debe ser conversation.item.retrieved.
event_id string Identificador del evento.
item RealtimeConversationResponseItem Elemento que se recuperó.

RealtimeServerEventConversationItemDeleted

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

Event structure

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

Properties

Field Type Description
type string 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 server_vad modo). 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

Field Type Description
type string 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 error eventos para que el cliente pueda identificar el elemento relacionado.

Event structure

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

Properties

Field Type Description
type string 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 object Detalles del error de transcripción.

Consulte las propiedades anidadas en la tabla siguiente.

Error properties

Field Type Description
type string 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 conversation.item.truncate evento . 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

Field Type Description
type string 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.

Event structure

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

Properties

Field Type Description
type string El tipo de evento debe ser error.
error object Detalles del error.

Consulte las propiedades anidadas en la tabla siguiente.

Error properties

Field Type Description
type string 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 input_audio_buffer.clear evento.

Event structure

{
  "type": "input_audio_buffer.cleared"
}

Properties

Field Type Description
type string El tipo de evento debe ser input_audio_buffer.cleared.

RealtimeServerEventInputAudioBufferCommitted

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

Event structure

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

Properties

Field Type Description
type string 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 server_vad modo 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).

Note

Es posible que el cliente quiera usar este evento para interrumpir la reproducción de audio o proporcionar comentarios visuales al usuario.

El cliente debe esperar recibir un input_audio_buffer.speech_stopped evento cuando se detiene la voz. La item_id propiedad es el identificador del elemento de mensaje de usuario creado cuando se detiene la voz. También item_id se incluye en el input_audio_buffer.speech_stopped evento 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

Field Type Description
type string 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 server_vad modo cuando el servidor detecta el final de la voz en el búfer de audio.

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

Event structure

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

Properties

Field Type Description
type string 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.

RealtimeServerEventOutputAudioBufferCleared

El evento de servidor output_audio_buffer.cleared se devuelve cuando se borra el búfer de audio de salida.

Note

Este evento solo es aplicable a WebRTC.

Esto sucede en modo VAD cuando el usuario ha interrumpido (input_audio_buffer.speech_started) o cuando el cliente ha emitido el output_audio_buffer.clear evento para cortar manualmente la respuesta de audio actual.

Event structure

{
  "type": "output_audio_buffer.cleared"
}

Properties

Field Type Description
type string El tipo de evento debe ser output_audio_buffer.cleared.
event_id string Identificador del evento de servidor.
response_id string Identificador único de la respuesta que generó el audio.

RealtimeServerEventOutputAudioBufferStarted

El evento de servidor output_audio_buffer.started se devuelve cuando el servidor comienza a transmitir audio al cliente. Este evento se genera después de agregar una parte de contenido de audio (response.content_part.added) a la respuesta.

Note

Este evento solo es aplicable a WebRTC.

Event structure

{
  "type": "output_audio_buffer.started",
  "event_id": "<item_id>",
  "response_id": "<response_id>"
}

Properties

Field Type Description
type string El tipo de evento debe ser output_audio_buffer.started.
event_id string Identificador del evento de servidor.
response_id string Identificador único de la respuesta que generó el audio.

RealtimeServerEventOutputAudioBufferStopped

El evento de servidor output_audio_buffer.stopped se devuelve cuando el búfer de audio de salida se ha purgado completamente en el servidor y no hay más audio disponible.

Note

Este evento solo es aplicable a WebRTC.

Este evento se devuelve después de que se hayan enviado los datos de respuesta completos al cliente a través del response.done evento .

Event structure

{
  "type": "output_audio_buffer.stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

Properties

Field Type Description
type string El tipo de evento debe ser output_audio_buffer.stopped.
event_id string Identificador del evento de servidor.
response_id string Identificador único de la respuesta que generó el audio.

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 tarifas 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

Field Type Description
type string 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.

Event structure

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

Properties

Field Type Description
type string 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 se interrumpe, incompleta o cancela una respuesta.

Event structure

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

Properties

Field Type Description
type string 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.

Event structure

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

Properties

Field Type Description
type string 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 se realiza en streaming.

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

Event structure

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

Properties

Field Type Description
type string 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 auxiliar durante la generación de respuesta.

Event structure

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

Properties

Field Type Description
type string 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.
part RealtimeContentPart Elemento de contenido que se agregó.

Part properties

Field Type Description
type RealtimeContentPartType

RealtimeServerEventResponseContentPartDone

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

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

Event structure

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

Properties

Field Type Description
type string 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.
part RealtimeContentPart Elemento de contenido que se realiza.

Part properties

Field Type Description
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.

Event structure

{
  "type": "response.created"
}

Properties

Field Type Description
type string El tipo de evento debe ser response.created.
response RealtimeResponse Objeto de respuesta.

RealtimeServerEventResponseDone

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

Event structure

{
  "type": "response.done"
}

Properties

Field Type Description
type string 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.

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

Field Type Description
type string 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 llamada de función generados por el modelo se realizan streaming.

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

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

Field Type Description
type string 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.
arguments 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 respuestas.

Event structure

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

Properties

Field Type Description
type string 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 se realiza la transmisión por secuencias de un elemento.

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

Event structure

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

Properties

Field Type Description
type string 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 se realiza la transmisión por secuencias.

RealtimeServerEventResponseTextDelta

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

Field Type Description
type string 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 se realiza streaming. El texto corresponde a la text parte de contenido de un elemento de mensaje del asistente.

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

Event structure

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

Properties

Field Type Description
type string 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.

Event structure

{
  "type": "session.created"
}

Properties

Field Type Description
type string 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 error evento en su lugar.

Event structure

{
  "type": "session.updated"
}

Properties

Field Type Description
type string El tipo de evento debe ser session.updated.
session RealtimeResponseSession Objeto de sesión.

Components

RealtimeAudioFormat

Allowed Values:

  • pcm16
  • g711_ulaw
  • g711_alaw

RealtimeAudioInputTranscriptionModel

Allowed Values:

  • whisper-1
  • gpt-4o-transcribe
  • gpt-4o-mini-transcribe
  • gpt-4o-transcribe-diarize
  • gpt-4o-mini-transcribe-2025-12-15

RealtimeAudioInputTranscriptionSettings

Field Type Description
language string Idioma del audio de entrada. Proporcionar el idioma de entrada en formato ISO-639-1 (como en) mejorará la precisión y la latencia.
model RealtimeAudioInputTranscriptionModel El modelo para la transcripción de entrada de audio. Por ejemplo, whisper-1.
prompt string Solicitud de la transcripción de entrada de audio. Texto opcional para guiar el estilo del modelo o continuar con un segmento de audio anterior. Para el modelo, el símbolo del whisper-1 sistema es una lista de palabras clave. En el caso de los modelos y gpt-4o-transcribe el modelo de la gpt-4o-transcribe-diarizeserie , el mensaje es una cadena de texto libre, como "esperar palabras relacionadas con la tecnología".

RealtimeAudioInputAudioNoiseReductionSettings

Field Type Description
type string Tipo de reducción de ruido. Especifique near_field para micrófonos de conversación cercana, como auriculares o far_field para micrófonos de campo lejano, como los micrófonos de la sala de conferencias o portátiles.

RealtimeClientEvent

Field Type Description
type RealtimeClientEventType Tipo del evento de cliente.
event_id string Identificador único del evento. El cliente puede especificar el identificador para ayudar a identificar el evento.

RealtimeClientEventType

Allowed Values:

  • 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

Field Type Description
type RealtimeContentPartType Tipo de contenido.

Propiedad del function objeto .

Valores permitidos: input_text, input_audio, item_reference, text.
text string Contenido de texto. Esta propiedad es aplicable a los input_text tipos de contenido 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 item_reference tipo de contenido en response.create eventos.
audio string Bytes de audio codificados en base64. Esta propiedad es aplicable al tipo de input_audio contenido.
transcript string Transcripción del audio. Esta propiedad es aplicable al tipo de input_audio contenido.

RealtimeContentPartType

Allowed Values:

  • input_text
  • input_audio
  • text
  • audio

RealtimeConversationItemBase

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

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

Field Type Description
id string Identificador único 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, function_call_output
object string Identificador del objeto de API que se devuelve. El valor siempre realtime.itemserá .
status RealtimeItemStatus Estado del elemento. Este campo no afecta a la conversación, pero se acepta para la coherencia con el conversation.item.created evento.

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

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

- Los elementos de mensaje del rol system solo input_text admiten contenido.
- Mensajes de elementos de compatibilidad user y input_text contenido de rolesinput_audio.
- Mensajes de elementos de contenido de compatibilidad assistant de rolestext.
call_id string Identificador de la llamada de función (para function_call y function_call_output elementos). Si se pasa en un function_call_output elemento, el servidor comprobará que existe un function_call elemento con el mismo identificador en el historial de conversaciones.
name string Nombre de la función a la que se llama (para function_call elementos).
arguments 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 se usa RealtimeConversationRequestItem para crear un nuevo elemento en la conversación a través del evento conversation.item.create .

Field Type Description
type RealtimeItemType Tipo del elemento.
id string Identificador único 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 RealtimeConversationResponseItem objeto representa un elemento de la conversación. Se usa en algunos de los eventos de servidor, como:

Field Type Description
object string Identificador del objeto de API devuelto.

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

Valores permitidos: message, function_call, function_call_output
id string Identificador único 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.

Field Type Description
type string Tipo de la herramienta.

Valores permitidos: function
name string Nombre de la función.
description string Descripción de la función, incluidas las directrices de uso. Por ejemplo, "Use esta función para obtener la hora actual".
parameters object Parámetros de la función en forma de un objeto JSON.

RealtimeItemStatus

Allowed Values:

  • in_progress
  • completed
  • incomplete

RealtimeItemType

Allowed Values:

  • message
  • function_call
  • function_call_output

RealtimeMessageRole

Allowed Values:

  • system
  • user
  • assistant

RealtimeRequestAssistantMessageItem

Field Type Description
role string Rol del mensaje.

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

RealtimeRequestAudioContentPart

Field Type Description
type string Tipo del elemento de contenido.

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

RealtimeRequestFunctionCallItem

Field Type Description
type string Tipo del elemento.

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

RealtimeRequestFunctionCallOutputItem

Field Type Description
type string 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

Field Type Description
type string Tipo del elemento.

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

RealtimeRequestMessageReferenceItem

Field Type Description
type string Tipo del elemento.

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

RealtimeRequestSession

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

Field Type Description
modalities 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.
instructions 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 de 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_noise_reduction RealtimeAudioInputAudioNoiseReductionSettings Configuración para la reducción del ruido de audio de entrada. Esto se puede establecer en null para desactivar. Reducción de ruido filtra el audio agregado al búfer de audio de entrada antes de enviarlo a VAD y al modelo. El filtrado del audio puede mejorar la precisión de la detección de turnos y VAD (lo que reduce los falsos positivos) y el rendimiento del modelo mejorando la percepción del audio de entrada.

Esta propiedad admite valores NULL.
input_audio_transcription RealtimeAudioInputTranscriptionSettings Configuración de la transcripción de audio de entrada. La configuración es null (off) de forma predeterminada. La transcripción de audio de entrada no es nativa del modelo, ya que el modelo consume audio directamente. La transcripción se ejecuta de forma asincrónica a través del /audio/transcriptions punto de conexión y debe tratarse como guía del contenido de audio de entrada en lugar de precisamente lo que el modelo oyó. Para obtener instrucciones adicionales sobre el servicio de transcripción, el cliente puede establecer opcionalmente el idioma y solicitar la transcripción.

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

Esta propiedad admite valores NULL.
tools 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, noney required. De lo contrario, puede especificar el nombre de la función que se va a usar.
temperature number Temperatura de muestreo del modelo. Los valores de temperatura permitidos se limitan a 0.6 a través de 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".

El valor predeterminado es "inf".

RealtimeRequestSystemMessageItem

Field Type Description
role string Rol del mensaje.

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

RealtimeRequestTextContentPart

Field Type Description
type string Tipo del elemento de contenido.

Valores permitidos: input_text
text string Contenido de texto.

RealtimeRequestUserMessageItem

Field Type Description
role string Rol del mensaje.

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

RealtimeResponse

Field Type Description
object string Objeto de respuesta.

Valores permitidos: realtime.response
id string Identificador único de la respuesta.
status RealtimeResponseStatus Estado de la respuesta.

El valor de 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.
usage object Estadísticas de uso de la respuesta. Cada sesión de API en tiempo real 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 usage objeto .
+ input_tokens integer Número de tokens de entrada usados en la respuesta, incluidos los tokens de texto y audio.

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

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

Propiedad del usage objeto .

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 input_token_details objeto .
+ text_tokens integer Número de tokens de texto usados en la respuesta.

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

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

Propiedad del usage objeto .

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

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

Propiedad del output_token_details objeto .

RealtimeResponseAudioContentPart

Field Type Description
type string Tipo del elemento de contenido.

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

Esta propiedad admite valores NULL.

RealtimeResponseBase

Recurso de respuesta.

RealtimeResponseFunctionCallItem

Field Type Description
type string Tipo del elemento.

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

RealtimeResponseFunctionCallOutputItem

Field Type Description
type string 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

Field Type Description
type string Tipo del elemento.

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

Elementos de matriz: RealtimeResponseTextContentPart
status RealtimeItemStatus Estado del elemento.

RealtimeResponseOptions

Field Type Description
modalities 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.
instructions 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 de 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.
tools 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.
temperature number Temperatura de muestreo del modelo. Los valores de temperatura permitidos se limitan a 0.6 a través de 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".

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

El auto valor (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.

El valor predeterminado 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 RealtimeResponseSession objeto representa una sesión en la API en tiempo real. Se usa en algunos de los eventos de servidor, como:

Field Type Description
object string Objeto de sesión.

Valores permitidos: realtime.session
id string Identificador único de la sesión.
model string Modelo usado para la sesión.
modalities 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.
instructions 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 de 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 turnos para la sesión.

Esta propiedad admite valores NULL.
tools 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.
temperature number Temperatura de muestreo del modelo. Los valores de temperatura permitidos se limitan a 0.6 a través de 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

Allowed Values:

  • in_progress
  • completed
  • cancelled
  • incomplete
  • failed

RealtimeResponseStatusDetails

Field Type Description
type RealtimeResponseStatus Estado de la respuesta.

RealtimeResponseTextContentPart

Field Type Description
type string Tipo del elemento de contenido.

Valores permitidos: text
text string Contenido de texto.

RealtimeServerEvent

Field Type Description
type RealtimeServerEventType Tipo del evento de servidor.
event_id string Identificador único del evento de servidor.

RealtimeServerEventRateLimitsUpdatedRateLimitsItem

Field Type Description
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.
remaining 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

Allowed Values:

  • 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

Field Type Description
type string Tipo de detección de turnos.

Valores permitidos: server_vad
threshold number Umbral de activación para la detección de turnos 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.

El valor predeterminado es 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) que se va a incluir antes del inicio de la voz detectada.

El valor predeterminado es 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 establece este valor en un número menor, pero podría cortar la última parte de la voz. Si establece este valor en un número mayor, el modelo esperará más tiempo para detectar el final de la voz, pero puede tardar más tiempo 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.

Field Type Description
type RealtimeToolType Tipo de la herramienta.

RealtimeToolChoice

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

RealtimeToolChoiceFunctionObject

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

Field Type Description
type string Tipo de .tool_choice

Valores permitidos: function
function object Herramienta de función que se va a seleccionar.

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

Propiedad del function objeto .

RealtimeToolChoiceLiteral

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

Allowed Values:

  • auto
  • none
  • required

RealtimeToolChoiceObject

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

Field Type Description
type RealtimeToolType Tipo de .tool_choice

RealtimeToolType

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

Allowed Values:

  • function

RealtimeTurnDetection

Field Type Description
type RealtimeTurnDetectionType Tipo de detección de turnos.

Valores permitidos: semantic_vad o server_vad
threshold number Umbral de activación para la detección de turnos de VAD del servidor (server_vad). 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.

El valor predeterminado es 0.5. Puede establecer el umbral en un valor entre 0.0 y 1.0.

Esta propiedad solo es aplicable a la server_vad detección de turnos.
prefix_padding_ms string Duración del audio de voz (en milisegundos) que se va a incluir antes del inicio de la voz detectada.

El valor predeterminado es 300 milisegundos.

Esta propiedad solo es aplicable a la server_vad detección de turnos.
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 establece este valor en un número menor, pero podría cortar la última parte de la voz. Si establece este valor en un número mayor, el modelo esperará más tiempo para detectar el final de la voz, pero puede tardar más tiempo en responder.

El valor predeterminado es 200 milisegundos.

Esta propiedad solo es aplicable a la server_vad detección de turnos.
create_response boolean Indica si el servidor creará automáticamente una respuesta cuando VAD esté habilitado y se detenga la voz.

El valor predeterminado es true.
interrupt_response boolean Indica si el servidor interrumpirá automáticamente cualquier respuesta en curso con la salida a la conversación predeterminada (auto) cuando se produzca un evento de inicio de VAD.

El valor predeterminado es true.
eagerness string El deseo del modelo de responder e interrumpir al usuario. Especifique low que espere más tiempo para que el usuario siga hablando. Especifique high para fragmentar el audio lo antes posible para respuestas más rápidas. El valor predeterminado es auto equivalente a medio.

Esta propiedad solo es aplicable a la semantic_vad detección de turnos.

RealtimeTurnDetectionType

Allowed Values:

  • semantic_vad - VAD semántico detecta cuándo el usuario ha terminado de hablar en función de las palabras que han dicho. El audio de entrada se puntua en función de la probabilidad de que el usuario haya terminado de hablar. Cuando la probabilidad es baja, el modelo esperará un tiempo de espera. Cuando la probabilidad es alta, no es necesario esperar.
  • server_vad - El servidor evalúa el audio de usuario del cliente. El servidor usa automáticamente ese audio para iniciar la generación de respuestas en las conversaciones aplicables cuando se detecta un final de voz.

RealtimeVoice

Allowed Values:

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

Related content

  • Last updated on