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

VAD: detección automática de voz

Lección 6 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Cómo funciona la detección de turnos
  2. Dos modos, un campo
  3. Eventos del VAD
  4. Incitar a un usuario en silencio: idle_timeout_ms
  5. Modo manual: turn_detection.type establecido en null
  6. Elige tu modo
  7. Puntos clave

Actualizado el 3 de noviembre de 2026, según la página Speech to Speech de xAI y la referencia de la API de Voz: la detección de turnos se configura con turn_detection.type ("server_vad" o null) y, opcionalmente, turn_detection.idle_timeout_ms. Fuentes: Speech to Speech · Voice API.

Cómo funciona la detección de turnos

En una conversación de voz, el sistema debe saber cuándo empieza a hablar el usuario y cuándo se calla. Esa es la función del VAD (detección de actividad de voz). La API de Agente de Voz de xAI ofrece un VAD en el servidor, server_vad: el servidor analiza el flujo de audio, detecta el final de cada intervención y desencadena la respuesta por sí mismo.

Dos modos, un campo

Eliges el modo en el objeto turn_detection de session.update:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": "server_vad" }
  }
}
turn_detection.typeQuién decide cuándo termina el turnoQué envías
"server_vad"El servidorinput_audio_buffer.append, nada más
nullTúinput_audio_buffer.append, luego input_audio_buffer.commit y response.create

En el modo server_vad, el servidor divide los turnos, confirma el audio e inicia la respuesta. Las interrupciones también se gestionan automáticamente: xAI recomienda este modo para una toma de turnos natural, cuando el usuario interrumpe al agente a mitad de frase. Sin embargo, la documentación no ofrece ningún ajuste de sensibilidad ni de duración del silencio: dividir los turnos es asunto del servidor.

Eventos del VAD

Con server_vad, el servidor informa de cada transición:

  • input_audio_buffer.speech_started: el VAD detectó el inicio del habla;
  • input_audio_buffer.speech_stopped: detectó el final;
  • input_audio_buffer.committed: el audio se confirmó como mensaje del usuario.
ws.on("message", (data) => {
  const event = JSON.parse(data);
  switch (event.type) {
    case "input_audio_buffer.speech_started":
      stopPlayback();       // el usuario está hablando: detén el audio del agente ya recibido
      break;
    case "input_audio_buffer.speech_stopped":
      showThinking();       // se detectó el final del habla: la respuesta está en camino
      break;
  }
});

En el lado del servidor, la interrupción es automática; en el lado del cliente, el audio que ya has recibido seguiría reproduciéndose si no lo detuvieras. speech_started es el momento adecuado para vaciar tu cola de reproducción.

Incitar a un usuario en silencio: idle_timeout_ms

El único ajuste documentado relacionado con el VAD, idle_timeout_ms, hace que el agente retome la conversación cuando el usuario guarda silencio tras una respuesta:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
  }
}

Si no se detecta habla durante ese tiempo después de que termine una respuesta, el servidor emite input_audio_buffer.timeout_triggered, confirma un turno de usuario en silencio y genera una comprobación. El temporizador se reinicia tras cada respuesta, por lo que se activa de nuevo cada idle_timeout_ms mientras el usuario no diga nada. Está desactivado por defecto (null). En una centralita telefónica, una comprobación tras unos segundos evita que los silencios se alarguen; escribe en tus instrucciones la frase de seguimiento que debe usar el agente.

Modo manual: turn_detection.type establecido en null

Para una interfaz de pulsar para hablar, o siempre que quieras decidir tú mismo cuándo termina un turno, establece el tipo en null:

{
  "type": "session.update",
  "session": {
    "turn_detection": { "type": null }
  }
}

A continuación, envías audio con input_audio_buffer.append y, cuando el usuario suelta el botón, envías input_audio_buffer.commit para confirmar el turno y response.create para solicitar la respuesta. input_audio_buffer.commit solo está disponible en modo manual. input_audio_buffer.clear descarta el audio enviado pero aún no confirmado, y response.cancel detiene una respuesta en curso, ya que la interrupción deja de ser automática en modo manual.

Elige tu modo

  • Conversación fluida (asistente, centralita telefónica, quiosco): server_vad, con idle_timeout_ms para incitar a usuarios en silencio si es necesario.
  • Walkie-talkie, dictado, entornos muy ruidosos: modo manual, donde el final del turno sigue al botón y el ruido de fondo no desencadena nada.

Puntos clave

  • turn_detection.type es "server_vad" (el servidor divide los turnos y gestiona las interrupciones) o null (modo manual).
  • La documentación de xAI no ofrece ningún umbral de sensibilidad ni duración de silencio para ajustar.
  • speech_started, speech_stopped y committed informan de las transiciones del VAD.
  • idle_timeout_ms incita a un usuario en silencio, con el evento input_audio_buffer.timeout_triggered.
  • En modo manual: append, luego commit y response.create.