Ir al contenido principal
Español— Elegir un idioma
Menú

Confirmar y vaciar el búfer de audio

Lección 8 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Gestión del búfer de audio
  2. input_audio_buffer.commit
  3. input_audio_buffer.clear
  4. Modo VAD frente a modo manual
  5. Puntos clave

Actualizado el 3 de noviembre de 2026, según la referencia de la API de voz de xAI: input_audio_buffer.commit solo está disponible cuando turn_detection.type es null; en el modo server_vad, el servidor confirma el audio por sí mismo. Fuente: Voice API.

Gestión del búfer de audio

Cuando envías audio mediante input_audio_buffer.append, los datos se acumulan en un búfer en el servidor. Dos operaciones controlan dicho búfer: commit para enviar su contenido como un mensaje de usuario y clear para vaciarlo sin procesarlo.

input_audio_buffer.commit

Este evento confirma el contenido actual del búfer de audio como un mensaje de usuario. Es obligatorio en modo manual (pulsar para hablar) y automático en modo VAD:

{
  "type": "input_audio_buffer.commit"
}

Cuando el servidor recibe una confirmación (commit):

  1. Crea un nuevo elemento de conversación con el audio acumulado
  2. Envía un evento input_audio_buffer.committed para confirmar la acción
  3. Envía un evento conversation.item.added con el nuevo elemento
  4. Comienza a transcribir el audio (si está habilitado)

La respuesta del servidor

{
  "type": "input_audio_buffer.committed",
  "item_id": "item_audio_001"
}

El item_id te permite hacer referencia a este mensaje en la conversación más adelante.

Cuándo confirmar manualmente

  • Pulsar para hablar: el usuario mantiene pulsado un botón para hablar y lo suelta para enviar
  • Segmentación manual: divides el flujo de audio en segmentos lógicos en el cliente
  • Integración telefónica: recibes fragmentos de audio de una centralita (PBX) y los confirmas al final de cada turno
// Ejemplo de pulsar para hablar
talkButton.addEventListener("mousedown", () => {
  isRecording = true;
  startCapture();
});

talkButton.addEventListener("mouseup", () => {
  isRecording = false;
  stopCapture();

  // Confirmar el búfer
  ws.send(JSON.stringify({
    type: "input_audio_buffer.commit"
  }));

  // Solicitar una respuesta
  ws.send(JSON.stringify({
    type: "response.create"
  }));
});

input_audio_buffer.clear

Este evento vacía el búfer de audio sin crear un mensaje en la conversación:

{
  "type": "input_audio_buffer.clear"
}

El servidor confirma la acción con:

{
  "type": "input_audio_buffer.cleared"
}

Cuándo vaciar el búfer

  • Cancelación: el usuario pulsa un botón «Cancelar» mientras habla
  • Interrupción: el usuario comienza a hablar, pero otro evento interrumpe el turno
  • Reinicio: tras un error o un tiempo de espera agotado, vacía el búfer antes de empezar de nuevo
  • Ruido de fondo: el sistema detecta que el búfer contiene solo ruido, no voz
cancelButton.addEventListener("click", () => {
  stopCapture();
  ws.send(JSON.stringify({
    type: "input_audio_buffer.clear"
  }));
  showMessage("Grabación cancelada");
});

Modo VAD frente a modo manual

En modo VAD (server_vad), el servidor gestiona todo el ciclo automáticamente:

  1. Detecta el inicio del habla (speech_started)
  2. Acumula el audio en el búfer
  3. Detecta el final del habla (speech_stopped)
  4. Confirma el búfer automáticamente
  5. Comienza a generar la respuesta automáticamente

En modo manual (turn_detection.type establecido en null), tú gestionas cada paso y es el único modo donde input_audio_buffer.commit está disponible:

  1. Envías audio con append
  2. Decides cuándo el usuario ha terminado
  3. Envías commit
  4. Envías response.create

Comparativa

AspectoModo VADModo manual
Detección de vozAutomáticaA tu cargo
Confirmación del búferAutomáticaManual (commit)
Solicitud de respuestaAutomáticaManual (response.create)
ControlMenos controlControl total
ComplejidadSencillaMás compleja
Casos de usoConversación fluidaPulsar para hablar, IVR

Puntos clave

  • input_audio_buffer.commit envía el búfer de audio como un mensaje de usuario
  • input_audio_buffer.clear vacía el búfer sin procesarlo
  • En modo VAD, la confirmación ocurre automáticamente cuando se detecta el final del habla
  • En modo manual (turn_detection.type establecido en null), debes enviar commit y luego response.create explícitamente; commit solo está disponible en este modo
  • El modo manual es adecuado para interfaces de pulsar para hablar y sistemas telefónicos IVR