VAD: detección automática de voz
En esta página
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"onull) 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.type | Quién decide cuándo termina el turno | Qué envías |
|---|---|---|
"server_vad" | El servidor | input_audio_buffer.append, nada más |
null | Tú | 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, conidle_timeout_mspara 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.typees"server_vad"(el servidor divide los turnos y gestiona las interrupciones) onull(modo manual).- La documentación de xAI no ofrece ningún umbral de sensibilidad ni duración de silencio para ajustar.
speech_started,speech_stoppedycommittedinforman de las transiciones del VAD.idle_timeout_msincita a un usuario en silencio, con el eventoinput_audio_buffer.timeout_triggered.- En modo manual:
append, luegocommityresponse.create.