Audio-Buffer festlegen und leeren
Auf dieser Seite
Aktualisiert am 3. November 2026, basierend auf der xAI Voice API-Referenz:
input_audio_buffer.commitsteht nur zur Verfügung, wennturn_detection.typeaufnullgesetzt ist. Imserver_vad-Modus übernimmt der Server das Festlegen des Audios selbst. Quelle: Voice API.
Verwaltung des Audio-Buffers
Wenn Sie Audio mit input_audio_buffer.append senden, wird die Datenmenge in einem Puffer auf dem Server angesammelt. Zwei Operationen steuern diesen Puffer: commit, um den Inhalt als Benutzernachricht einzureichen, und clear, um ihn ohne Verarbeitung zu leeren.
input_audio_buffer.commit
Dieses Ereignis legt den aktuellen Inhalt des Audio-Buffers als Benutzernachricht fest. Es ist im manuellen Modus (Push-to-Talk) erforderlich und im VAD-Modus automatisch:
{
"type": "input_audio_buffer.commit"
}
Wenn der Server ein Commit-Ereignis empfängt, führt er folgende Schritte aus:
- Er erstellt einen neuen Gesprächsartikel mit dem angesammelten Audio.
- Er sendet ein
input_audio_buffer.committed-Ereignis zur Bestätigung. - Er sendet ein
conversation.item.added-Ereignis mit dem neuen Artikel. - Er beginnt mit der Transkription des Audios (sofern aktiviert).
Die Antwort des Servers
{
"type": "input_audio_buffer.committed",
"item_id": "item_audio_001"
}
Mit der item_id können Sie diese Nachricht später im Gespräch referenzieren.
Wann man manuell festlegt
- Push-to-Talk: Der Benutzer hält eine Taste zum Sprechen gedrückt und gibt sie los, um zu senden.
- Manuelle Segmentierung: Sie teilen den Audio-Stream auf dem Client in logische Segmente auf.
- Telefonintegration: Sie erhalten Audio-Blöcke von einer PBX und legen sie am Ende jeder Runde fest.
// Beispiel für Push-to-Talk
talkButton.addEventListener("mousedown", () => {
isRecording = true;
startCapture();
});
talkButton.addEventListener("mouseup", () => {
isRecording = false;
stopCapture();
// Den Puffer festlegen
ws.send(JSON.stringify({
type: "input_audio_buffer.commit"
}));
// Eine Antwort anfordern
ws.send(JSON.stringify({
type: "response.create"
}));
});
input_audio_buffer.clear
Dieses Ereignis leert den Audio-Buffer, ohne eine Nachricht im Gespräch zu erstellen:
{
"type": "input_audio_buffer.clear"
}
Der Server bestätigt dies mit:
{
"type": "input_audio_buffer.cleared"
}
Wann man leert
- Abbruch: Der Benutzer drückt eine „Abbrechen”-Taste, während er spricht.
- Unterbrechung: Der Benutzer beginnt zu sprechen, und ein anderes Ereignis unterbricht die Runde.
- Neustart: Nach einem Fehler oder einem Timeout den Puffer leeren, bevor man von vorne beginnt.
- Hintergrundgeräusche: Das System erkennt, dass der Puffer nur Rauschen und keine Sprache enthält.
cancelButton.addEventListener("click", () => {
stopCapture();
ws.send(JSON.stringify({
type: "input_audio_buffer.clear"
}));
showMessage("Aufnahme abgebrochen");
});
VAD-Modus versus manueller Modus
Im VAD-Modus (server_vad) übernimmt der Server den gesamten Zyklus automatisch:
- Er erkennt den Beginn der Sprache (
speech_started). - Er sammelt das Audio im Puffer.
- Er erkennt das Ende der Sprache (
speech_stopped). - Er legt den Puffer automatisch fest.
- Er beginnt automatisch mit der Generierung der Antwort.
Im manuellen Modus (turn_detection.type auf null gesetzt) führen Sie jeden Schritt selbst aus, und dies ist der einzige Modus, in dem input_audio_buffer.commit verfügbar ist:
- Sie senden Audio mit
append. - Sie entscheiden, wann der Benutzer fertig ist.
- Sie senden
commit. - Sie senden
response.create.
Vergleich
| Aspekt | VAD-Modus | Manueller Modus |
|---|---|---|
| Spracherkennung | Automatisch | In Ihrer Verantwortung |
| Puffer festlegen | Automatisch | Manuell (commit) |
| Antwortanfrage | Automatisch | Manuell (response.create) |
| Kontrolle | Weniger Kontrolle | Volle Kontrolle |
| Komplexität | Einfach | Komplexer |
| Anwendungsfälle | Freier Gesprächsverlauf | Push-to-Talk, IVR |
Kernaussagen
input_audio_buffer.commitreicht den Audio-Buffer als Benutzernachricht ein.input_audio_buffer.clearleert den Puffer ohne Verarbeitung.- Im VAD-Modus erfolgt das Festlegen automatisch, wenn das Ende der Sprache erkannt wird.
- Im manuellen Modus (
turn_detection.typeaufnullgesetzt) müssen Siecommitund anschließendresponse.createexplizit senden;commitsteht nur in diesem Modus zur Verfügung. - Der manuelle Modus eignet sich für Push-to-Talk-Oberflächen und IVR-Telefonsysteme.