Zatwierdzanie i czyszczenie bufora audio
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie dokumentacji referencyjnej xAI Voice API:
input_audio_buffer.commitjest dostępne wyłącznie, gdyturn_detection.typema wartośćnull; w trybieserver_vadserwer sam zatwierdza audio. Źródło: Voice API.
Zarządzanie buforem audio
Gdy wysyłasz dane audio za pomocą input_audio_buffer.append, są one gromadzone w buforze na serwerze. Dwie operacje kontrolują ten bufor: commit (zatwierdź), aby przesłać jego zawartość jako wiadomość użytkownika, oraz clear (wyczyść), aby opróżnić go bez przetwarzania.
input_audio_buffer.commit
To zdarzenie zatwierdza bieżącą zawartość bufora audio jako wiadomość użytkownika. Jest wymagane w trybie ręcznym (push-to-talk) i automatyczne w trybie VAD:
{
"type": "input_audio_buffer.commit"
}
Gdy serwer otrzyma polecenie zatwierdzenia:
- Tworzy nowy element konwersacji z nagromadzonym audio
- Wysyła zdarzenie
input_audio_buffer.committedjako potwierdzenie - Wysyła zdarzenie
conversation.item.addedz nowym elementem - Rozpoczyna transkrypcję audio (jeśli jest włączona)
Odpowiedź serwera
{
"type": "input_audio_buffer.committed",
"item_id": "item_audio_001"
}
Pole item_id pozwala odwołać się do tej wiadomości w konwersacji w późniejszym czasie.
Kiedy zatwierdzać ręcznie
- Push-to-talk: użytkownik przytrzymuje przycisk, aby mówić, i puszcza go, aby wysłać nagranie
- Ręczna segmentacja: dzielisz strumień audio na logiczne segmenty po stronie klienta
- Integracja telefoniczna: otrzymujesz fragmenty audio z centrali PBX i zatwierdzasz je na końcu każdej tury rozmowy
// Przykład push-to-talk
talkButton.addEventListener("mousedown", () => {
isRecording = true;
startCapture();
});
talkButton.addEventListener("mouseup", () => {
isRecording = false;
stopCapture();
// Zatwierdź bufor
ws.send(JSON.stringify({
type: "input_audio_buffer.commit"
}));
// Żądaj odpowiedzi
ws.send(JSON.stringify({
type: "response.create"
}));
});
input_audio_buffer.clear
To zdarzenie opróżnia bufor audio bez tworzenia wiadomości w konwersacji:
{
"type": "input_audio_buffer.clear"
}
Serwer potwierdza to wysyłając:
{
"type": "input_audio_buffer.cleared"
}
Kiedy czyścić bufor
- Anulowanie: użytkownik naciska przycisk „Anuluj“ podczas mówienia
- Przerwanie: użytkownik zaczyna mówić, ale inne zdarzenie przerywa turę
- Reset: po błędzie lub upływie czasu wyczyść bufor przed rozpoczęciem od nowa
- Szum tła: system wykrywa, że bufor zawiera tylko szum, a nie mowę
cancelButton.addEventListener("click", () => {
stopCapture();
ws.send(JSON.stringify({
type: "input_audio_buffer.clear"
}));
showMessage("Nagrywanie anulowane");
});
Tryb VAD a tryb ręczny
W trybie VAD (server_vad) serwer obsługuje cały cykl automatycznie:
- Wykrywa początek mowy (
speech_started) - Gromadzi audio w buforze
- Wykrywa koniec mowy (
speech_stopped) - Automatycznie zatwierdza bufor
- Automatycznie rozpoczyna generowanie odpowiedzi
W trybie ręcznym (gdy turn_detection.type jest ustawione na null) samodzielnie obsługujesz każdy krok; jest to jedyny tryb, w którym dostępne jest input_audio_buffer.commit:
- Wysyłasz audio za pomocą
append - Decydujesz, kiedy użytkownik skończył mówić
- Wysyłasz
commit - Wysyłasz
response.create
Porównanie
| Aspekt | Tryb VAD | Tryb ręczny |
|---|---|---|
| Wykrywanie mowy | Automatyczne | Zależy od Ciebie |
| Zatwierdzanie bufora | Automatyczne | Ręczne (commit) |
| Żądanie odpowiedzi | Automatyczne | Ręczne (response.create) |
| Kontrola | Mniejsza kontrola | Pełna kontrola |
| Złożoność | Proste | Bardziej złożone |
| Przypadki użycia | Swobodna rozmowa | Push-to-talk, IVR |
Kluczowe wnioski
input_audio_buffer.commitprzesyła bufor audio jako wiadomość użytkownikainput_audio_buffer.clearopróżnia bufor bez przetwarzania- W trybie VAD zatwierdzenie następuje automatycznie po wykryciu końca mowy
- W trybie ręcznym (gdy
turn_detection.typejest ustawione nanull) musisz jawnie wysłaćcommit, a następnieresponse.create; poleceniecommitjest dostępne tylko w tym trybie - Tryb ręczny sprawdza się w interfejsach push-to-talk i telefonicznych systemach IVR