Referencia de api dinámica de voz

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

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

Características clave

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

Eventos de cliente

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

session.update

Actualice la configuración de la sesión. Este evento se puede enviar en cualquier momento para modificar la configuración, como voz, modalidades, detección de turnos, herramientas y otros parámetros de sesión. Tenga en cuenta que una vez que se inicializa una sesión con un modelo determinado, no se puede cambiar a otro modelo.

Estructura de eventos

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

Propiedades

Ejemplo con Voz personalizada de Azure

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

session.avatar.connect

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

Estructura de eventos

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

Propiedades

input_audio_buffer.append

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

Estructura de eventos

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

Propiedades

input_audio_buffer.commit

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

Estructura de eventos

{
  "type": "input_audio_buffer.commit"
}

Propiedades

input_audio_buffer.clear

Borre el búfer de audio de entrada.

Estructura de eventos

{
  "type": "input_audio_buffer.clear"
}

Propiedades

conversation.item.create

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

Estructura de eventos

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

Propiedades

Ejemplo con contenido de audio

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

Ejemplo con llamada de función

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call",
    "name": "get_weather",
    "call_id": "call_123",
    "arguments": "{\"location\": \"San Francisco\", \"unit\": \"celsius\"}"
  }
}

Ejemplo con llamada MCP

{
  "type": "conversation.item.create",
  "item": {
    "type": "mcp_call",
    "approval_request_id": null,
    "arguments": "",
    "server_label": "deepwiki",
    "name": "ask_question",
    "output": null,
    "error": null
  }
}

conversation.item.retrieve

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

Estructura de eventos

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

Propiedades

conversation.item.truncate

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

Estructura de eventos

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

Propiedades

conversation.item.delete

Quite un elemento del historial de conversaciones.

Estructura de eventos

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

Propiedades

response.create

Indique al servidor que cree una respuesta a través de la inferencia del modelo. Este evento puede especificar la configuración específica de la respuesta que invalida los valores predeterminados de la sesión.

Estructura de eventos

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

Propiedades

Ejemplo con opción de herramienta

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

Ejemplo con animación

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

response.cancel

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

Estructura de eventos

{
  "type": "response.cancel"
}

Propiedades

Propiedades

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.

Estructura de eventos

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

Propiedades

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 .

Estructura de eventos

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

Propiedades

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 .

Estructura de eventos

{
  "type": "input_audio_buffer.clear"
}

Propiedades

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 .

Estructura de eventos

{
  "type": "input_audio_buffer.commit"
}

Propiedades

RealtimeClientEventResponseCancel

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

El servidor responderá con un response.done evento con un estado de response.status=cancelled.

Estructura de eventos

{
  "type": "response.cancel"
}

Propiedades

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.

Estructura de eventos

{
  "type": "response.create"
}

Propiedades

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.

Estructura de eventos

{
  "type": "session.update"
}

Propiedades

Eventos de servidor

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

session.created

Se envía cuando se establece correctamente una nueva sesión. Este es el primer evento recibido después de conectarse a la API.

Estructura de eventos

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

Propiedades

session.updated

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

Estructura de eventos

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

Propiedades

session.avatar.connecting

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

Estructura de eventos

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

Propiedades

conversation.item.created

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

Estructura de eventos

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

Propiedades

Ejemplo con elemento de audio

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

conversation.item.retrieved

Se envía en respuesta a un conversation.item.retrieve evento de cliente, proporcionando el elemento de conversación solicitado.

Propiedades

conversation.item.truncated

El evento de servidor conversation.item.truncated se devuelve cuando el cliente trunca un elemento de mensaje de audio del asistente anterior con un 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.

Estructura de eventos

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

Propiedades

conversation.item.deleted

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

Estructura de eventos

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

Propiedades

response.created

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

Estructura de eventos

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

Propiedades

response.done

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

Estructura de eventos

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

Propiedades

response.output_item.added

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

Estructura de eventos

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

Propiedades

response.output_item.done

Se envía cuando se completa un elemento de salida.

Estructura de eventos

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

Propiedades

response.content_part.added

El evento de servidor response.content_part.added se devuelve cuando se agrega una nueva parte de contenido a un elemento de mensaje auxiliar durante la generación de respuesta.

Estructura de eventos

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

Propiedades

response.content_part.done

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.

Estructura de eventos

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

Propiedades

response.text.delta

Streaming de contenido de texto desde el modelo. Enviado incrementalmente a medida que el modelo genera texto.

Estructura de eventos

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

Propiedades

response.text.done

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

Estructura de eventos

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

Propiedades

response.audio.delta

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

Estructura de eventos

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

Propiedades

response.audio.done

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

Estructura de eventos

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

Propiedades

response.audio_transcript.delta

Transcripción de streaming del contenido de audio generado.

Estructura de eventos

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

Propiedades

response.audio_transcript.done

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

Estructura de eventos

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

Propiedades

conversation.item.input_audio_transcription.completed

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

La transcripción comienza cuando el cliente o el servidor confirman el búfer de audio de entrada (en 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.

Estructura de eventos

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

Propiedades

conversation.item.input_audio_transcription.delta

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

Estructura de eventos

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

Propiedades

conversation.item.input_audio_transcription.failed

El evento de servidor conversation.item.input_audio_transcription.failed se devuelve cuando se configura la transcripción de audio de entrada y se produce un error en una solicitud de transcripción para un mensaje de usuario. Este evento es independiente de otros error eventos 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

Propiedades de error

response.animation_blendshapes.delta

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

Estructura de eventos

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

Propiedades

response.animation_blendshapes.done

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

Estructura de eventos

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

Propiedades

response.audio_timestamp.delta

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

Estructura de eventos

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

Propiedades

response.audio_timestamp.done

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

Estructura de eventos

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

Propiedades

response.animation_viseme.delta

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

Estructura de eventos

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

Propiedades

response.animation_viseme.done

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

Estructura de eventos

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

Propiedades

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

error

El evento de servidor error se devuelve cuando se produce un error, que podría ser un problema de cliente o un problema de servidor. La mayoría de los errores se pueden recuperar y la sesión permanece abierta.

Estructura de eventos

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

Propiedades

Propiedades de error

input_audio_buffer.cleared

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

Estructura de eventos

{
  "type": "input_audio_buffer.cleared"
}

Propiedades

input_audio_buffer.committed

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.

Estructura de eventos

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

Propiedades

input_audio_buffer.speech_started

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

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.

Estructura de eventos

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

Propiedades

input_audio_buffer.speech_stopped

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.

Estructura de eventos

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

Propiedades

rate_limits.updated

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

Cuando se crea una respuesta, algunos tokens se reservan para los tokens de salida. Los límites de tarifas 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

response.audio.delta

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

response.audio.done

El evento de servidor response.audio.done se devuelve cuando se realiza el audio generado por el modelo.

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

Estructura de eventos

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

Propiedades

response.audio_transcript.delta

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

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

response.audio_transcript.done

El evento de servidor response.audio_transcript.done se devuelve cuando la transcripción generada por el modelo de salida de audio se realiza en streaming.

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

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

response.function_call_arguments.delta

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

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

response.function_call_arguments.done

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.

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

mcp_list_tools.in_progress

El evento de servidor mcp_list_tools.in_progress se devuelve cuando el servicio comienza a enumerar las herramientas disponibles desde un servidor mcp.

Estructura de eventos

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

Propiedades

mcp_list_tools.completed

El evento de servidor mcp_list_tools.completed se devuelve cuando el servicio completa la lista de herramientas disponibles de un servidor mcp.

Estructura de eventos

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

Propiedades

mcp_list_tools.failed

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

Estructura de eventos

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

Propiedades

response.mcp_call_arguments.delta

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

Estructura de eventos

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

Propiedades

response.mcp_call_arguments.done

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

Estructura de eventos

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

Propiedades

response.mcp_call.in_progress

El evento de servidor response.mcp_call.in_progress se devuelve cuando una llamada a la herramienta MCP comienza el procesamiento.

Estructura de eventos

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

Propiedades

response.mcp_call.completed

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

Estructura de eventos

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

Propiedades

response.mcp_call.failed

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

Estructura de eventos

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

Propiedades

response.output_item.added

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

Estructura de eventos

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

Propiedades

response.output_item.done

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.

Estructura de eventos

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

Propiedades

response.text.delta

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

response.text.done

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.

Estructura de eventos

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

Propiedades

Components

Formatos de audio

RealtimeAudioFormat

Formato de audio base usado para el audio de entrada.

Valores permitidos:

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

RealtimeOutputAudioFormat

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

Valores permitidos:

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

RealtimeAudioInputTranscriptionSettings

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

RealtimeInputAudioNoiseReductionSettings

Esto puede ser:

• Objeto RealtimeOpenAINoiseReduction
• Un objeto RealtimeAzureDeepNoiseSuppression

RealtimeOpenAINoiseReduction

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

RealtimeAzureDeepNoiseSuppression

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

RealtimeInputAudioEchoCancellationSettings

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

Configuración de voz

RealtimeVoice

Unión de todas las configuraciones de voz admitidas.

Esto puede ser:

• Un objeto RealtimeOpenAIVoice
• Un objeto RealtimeAzureVoice

RealtimeOpenAIVoice

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

RealtimeAzureVoice

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

RealtimeAzureStandardVoice

Configuración de voz estándar de Azure.

RealtimeAzureCustomVoice

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

Ejemplo:

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

RealtimeAzurePersonalVoice

Configuración de voz personal de Azure.

Detección de turnos

RealtimeTurnDetection

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

RealtimeServerVAD

Detección de turnos basada en VAD base.

RealtimeOpenAISemanticVAD

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

RealtimeAzureSemanticVAD

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

RealtimeAzureSemanticVADMultilingual

VAD semántico de Azure (variante predeterminada).

RealtimeEOUDetection

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

Configuración del avatar

RealtimeAvatarConfig

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

RealtimeIceServer

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

RealtimeVideoParams

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

RealtimeVideoCrop

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

RealtimeVideoResolution

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

Configuración de animación

RealtimeAnimation

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

RealtimeAnimationOutputType

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

Valores permitidos:

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

Configuración de sesión

RealtimeRequestSession

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

RealtimeModality

Modalidades de sesión admitidas.

Valores permitidos:

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

RealtimeAudioTimestampType

Tipos de marca de tiempo de salida admitidos en el contenido de respuesta de audio.

Valores permitidos:

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

Configuración de herramientas

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

RealtimeTool

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

RealtimeToolChoice

Estrategia de selección de herramientas.

Esto puede ser:

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

MCPTool

Configuración de la herramienta MCP.

RealtimeConversationResponseItem

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

RealtimeConversationUserMessageItem

Elemento de mensaje de usuario.

RealtimeConversationAssistantMessageItem

Elemento de mensaje del asistente.

RealtimeConversationSystemMessageItem

Elemento de mensaje del sistema.

RealtimeConversationFunctionCallItem

Elemento de solicitud de llamada de función.

RealtimeConversationFunctionCallOutputItem

Elemento de respuesta de llamada de función.

RealtimeConversationMCPListToolsItem

Elemento de respuesta de las herramientas de lista de MCP.

RealtimeConversationMCPCallItem

Elemento de respuesta de llamada de MCP.

RealtimeConversationMCPApprovalRequestItem

Elemento de solicitud de aprobación de MCP.

RealtimeItemStatus

Estado de los elementos de conversación.

Valores permitidos:

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

RealtimeContentPart

Elemento de contenido dentro de un mensaje.

RealtimeInputTextContentPart

Elemento de contenido de texto.

RealtimeOutputTextContentPart

Elemento de contenido de texto.

RealtimeInputAudioContentPart

Elemento de contenido de audio.

RealtimeOutputAudioContentPart

Elemento de contenido de audio.

Objetos de respuesta

RealtimeResponse

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

RealtimeResponseStatus

Valores de estado de respuesta.

Valores permitidos:

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

RealtimeUsage

Estadísticas de uso de tokens.

TokenDetails

Desglose detallado del uso de tokens.

Tratamiento de errores

RealtimeErrorDetails

Objeto de información de error.

RealtimeConversationRequestItem

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

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

RealtimeSystemMessageItem

Un elemento de mensaje del sistema.

RealtimeUserMessageItem

Un elemento de mensaje de usuario.

RealtimeAssistantMessageItem

Elemento de mensaje del asistente.

RealtimeFunctionCallItem

Un elemento de llamada de función.

RealtimeFunctionCallOutputItem

Un elemento de salida de llamada de función.

RealtimeMCPApprovalResponseItem

Un elemento de respuesta de aprobación de MCP.

RealtimeFunctionTool

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

RealtimeItemStatus

Valores permitidos:

• in_progress
• completed
• incomplete

RealtimeResponseAudioContentPart

RealtimeResponseFunctionCallItem

RealtimeResponseFunctionCallOutputItem

RealtimeResponseOptions

RealtimeResponseSession

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

• session.created
• session.updated

RealtimeResponseStatusDetails

RealtimeRateLimitsItem

Recursos relacionados

• Pruebe el inicio rápido de Voz en vivo
• Prueba el inicio rápido de los agentes de voz en directo
• Más información sobre cómo usar voice live API