Confirmar e limpar o buffer de áudio
Nesta página
Atualizado em 3 de novembro de 2026, com base na referência da API de Voz da xAI:
input_audio_buffer.commitsó está disponível quandoturn_detection.typeénull; no modoserver_vad, o servidor confirma o áudio automaticamente. Fonte: Voice API.
Gestão do buffer de áudio
Quando envia áudio através de input_audio_buffer.append, os dados acumulam-se num buffer no servidor. Duas operações controlam esse buffer: commit para submeter o seu conteúdo como uma mensagem do utilizador e clear para o esvaziar sem processamento.
input_audio_buffer.commit
Este evento confirma o conteúdo atual do buffer de áudio como uma mensagem do utilizador. É obrigatório no modo manual (push-to-talk) e automático no modo VAD:
{
"type": "input_audio_buffer.commit"
}
Quando o servidor recebe um commit, ele:
- Cria um novo item de conversação com o áudio acumulado
- Envia um evento
input_audio_buffer.committedpara confirmar - Envia um evento
conversation.item.addedcom o novo item - Inicia a transcrição do áudio (se ativada)
A resposta do servidor
{
"type": "input_audio_buffer.committed",
"item_id": "item_audio_001"
}
O item_id permite-lhe referenciar esta mensagem na conversação posteriormente.
Quando confirmar manualmente
- Push-to-talk: o utilizador mantém um botão premido para falar e solta-o para enviar
- Segmentação manual: divide o fluxo de áudio em segmentos lógicos no cliente
- Integração telefónica: recebe blocos de áudio de um PBX e confirma-os no final de cada turno
// Exemplo de push-to-talk
talkButton.addEventListener("mousedown", () => {
isRecording = true;
startCapture();
});
talkButton.addEventListener("mouseup", () => {
isRecording = false;
stopCapture();
// Confirmar o buffer
ws.send(JSON.stringify({
type: "input_audio_buffer.commit"
}));
// Solicitar uma resposta
ws.send(JSON.stringify({
type: "response.create"
}));
});
input_audio_buffer.clear
Este evento esvazia o buffer de áudio sem criar uma mensagem na conversação:
{
"type": "input_audio_buffer.clear"
}
O servidor confirma com:
{
"type": "input_audio_buffer.cleared"
}
Quando limpar
- Cancelamento: o utilizador prime o botão “Cancelar” enquanto fala
- Interrupção: o utilizador começa a falar, mas outro evento interrompe o turno
- Reinício: após um erro ou tempo limite, limpe o buffer antes de recomeçar
- Ruído de fundo: o sistema deteta que o buffer contém apenas ruído, sem fala
cancelButton.addEventListener("click", () => {
stopCapture();
ws.send(JSON.stringify({
type: "input_audio_buffer.clear"
}));
showMessage("Gravação cancelada");
});
Modo VAD versus modo manual
No modo VAD (server_vad), o servidor gere todo o ciclo automaticamente:
- Deteta o início da fala (
speech_started) - Acumula o áudio no buffer
- Deteta o fim da fala (
speech_stopped) - Confirma o buffer automaticamente
- Inicia a geração da resposta automaticamente
No modo manual (turn_detection.type definido como null), gere cada passo manualmente; este é o único modo onde input_audio_buffer.commit está disponível:
- Envia áudio com
append - Decide quando o utilizador terminou
- Envia
commit - Envia
response.create
Comparação
| Aspeto | Modo VAD | Modo manual |
|---|---|---|
| Deteção de fala | Automática | A seu cargo |
| Confirmação do buffer | Automática | Manual (commit) |
| Pedido de resposta | Automático | Manual (response.create) |
| Controlo | Menos controlo | Controlo total |
| Complexidade | Simples | Mais complexo |
| Casos de uso | Conversação fluida | Push-to-talk, IVR |
Pontos-chave
input_audio_buffer.commitsubmete o buffer de áudio como uma mensagem do utilizadorinput_audio_buffer.clearesvazia o buffer sem processamento- No modo VAD, a confirmação ocorre automaticamente quando é detetado o fim da fala
- No modo manual (
turn_detection.typedefinido comonull), deve enviar explicitamentecommite depoisresponse.create;commitsó está disponível neste modo - O modo manual é adequado para interfaces push-to-talk e sistemas telefónicos IVR