Esegui il commit e svuota il buffer audio
In questa pagina
Aggiornato il 3 novembre 2026, in base al riferimento dell’API Voice di xAI:
input_audio_buffer.commitè disponibile solo quandoturn_detection.typeènull; in modalitàserver_vad, il server esegue il commit dell’audio automaticamente. Fonte: Voice API.
Gestione del buffer audio
Quando invii audio con input_audio_buffer.append, i dati si accumulano in un buffer sul server. Due operazioni controllano questo buffer: commit per inviare il contenuto come messaggio utente e clear per svuotarlo senza elaborazione.
input_audio_buffer.commit
Questo evento esegue il commit del contenuto corrente del buffer audio come messaggio utente. È obbligatorio in modalità manuale (push-to-talk) e automatico in modalità VAD:
{
"type": "input_audio_buffer.commit"
}
Quando il server riceve un commit:
- Crea un nuovo elemento di conversazione con l’audio accumulato
- Invia un evento
input_audio_buffer.committedper confermare - Invia un evento
conversation.item.addedcon il nuovo elemento - Avvia la trascrizione dell’audio (se abilitata)
La risposta del server
{
"type": "input_audio_buffer.committed",
"item_id": "item_audio_001"
}
L’item_id ti permette di fare riferimento a questo messaggio nella conversazione in un secondo momento.
Quando eseguire il commit manualmente
- Push-to-talk: l’utente tiene premuto un pulsante per parlare e lo rilascia per inviare
- Segmentazione manuale: suddividi il flusso audio in segmenti logici lato client
- Integrazione telefonica: ricevi chunk audio da un PBX ed esegui il commit alla fine di ogni turno
// Esempio push-to-talk
talkButton.addEventListener("mousedown", () => {
isRecording = true;
startCapture();
});
talkButton.addEventListener("mouseup", () => {
isRecording = false;
stopCapture();
// Esegui il commit del buffer
ws.send(JSON.stringify({
type: "input_audio_buffer.commit"
}));
// Richiedi una risposta
ws.send(JSON.stringify({
type: "response.create"
}));
});
input_audio_buffer.clear
Questo evento svuota il buffer audio senza creare un messaggio nella conversazione:
{
"type": "input_audio_buffer.clear"
}
Il server conferma con:
{
"type": "input_audio_buffer.cleared"
}
Quando svuotare il buffer
- Annullamento: l’utente preme un pulsante “Annulla” mentre parla
- Interruzione: l’utente inizia a parlare, ma un altro evento interrompe il turno
- Reset: dopo un errore o un timeout, svuota il buffer prima di ricominciare
- Rumore di fondo: il sistema rileva che il buffer contiene solo rumore, non voce
cancelButton.addEventListener("click", () => {
stopCapture();
ws.send(JSON.stringify({
type: "input_audio_buffer.clear"
}));
showMessage("Registrazione annullata");
});
Modalità VAD rispetto alla modalità manuale
In modalità VAD (server_vad), il server gestisce l’intero ciclo automaticamente:
- Rileva l’inizio della voce (
speech_started) - Accumula l’audio nel buffer
- Rileva la fine della voce (
speech_stopped) - Esegue il commit del buffer automaticamente
- Avvia automaticamente la generazione della risposta
In modalità manuale (turn_detection.type impostato su null), gestisci ogni passo tu stesso; è l’unica modalità in cui input_audio_buffer.commit è disponibile:
- Invii l’audio con
append - Decidi quando l’utente ha finito
- Invii
commit - Invii
response.create
Confronto
| Aspetto | Modalità VAD | Modalità manuale |
|---|---|---|
| Rilevamento voce | Automatico | A tua cura |
| Commit del buffer | Automatico | Manuale (commit) |
| Richiesta risposta | Automatica | Manuale (response.create) |
| Controllo | Minore controllo | Controllo totale |
| Complessità | Semplice | Più complessa |
| Casi d’uso | Conversazione fluida | Push-to-talk, IVR |
Punti chiave
input_audio_buffer.commitinvia il buffer audio come messaggio utenteinput_audio_buffer.clearsvuota il buffer senza elaborazione- In modalità VAD, il commit avviene automaticamente al rilevamento della fine della voce
- In modalità manuale (
turn_detection.typeimpostato sunull), devi inviare esplicitamentecommite poiresponse.create;commitè disponibile solo in questa modalità - La modalità manuale è adatta alle interfacce push-to-talk e ai sistemi telefonici IVR