Änderungen und Deprecation: was sich ändert, wann und wie du es erfährst

Wenn du auf der API aufbaust, ist diese Seite die feste Adresse für eine Frage: Was kann sich unter mir ändern, und woher erfahre ich es? Die Adresse wird sich nicht ändern.

Das Versprechen

Heute hat die API eine Version, /v1. Darin gilt:

• Nichts wird ohne Vorankündigung entfernt, umbenannt oder in seinem Typ geändert. Ein Feld, das du heute liest, behält seinen Namen, seinen Typ und seine Bedeutung.
• Neue Felder kommen hinter einem Opt-in. Eine Antwort, die du schon parst, bekommt keinen Schlüssel, den du nicht angefordert hast: round und measureStatus sind die ersten beiden Opt-ins, und ohne sie sind deine Antworten Byte für Byte das, was sie waren. Muss ein Feld jemals in der Standardantwort erscheinen, wird es zuerst im Changelog angekündigt und kommt als ein neuer Schlüssel, nie innerhalb eines bestehenden Objekts.
• Fehlercodes behalten ihre Bedeutung. Eine neue Situation kann einen neuen Code bekommen, also verzweige auf error.code und halte einen Default für Codes bereit, die du nicht kennst. Verzweige nie auf den Wortlaut von message.

Was als Änderung zählt

Passiert jederzeit	Zuerst angekündigt, mit mindestens 90 Tagen
Eine neue Route	Ein Feld entfernen oder umbenennen
Eine neue Opt-in-Option	Typ, Einheit oder Bedeutung eines Felds ändern
Ein neuer Status, eine neue Marge oder eine neue Erklärung in der Dokumentation	Eine Route oder eine Option entfernen
Eine schnellere Analyse mit denselben Zahlen	Eine Regel, die bisher nicht durchgesetzt wurde, wird durchgesetzt
Ein neuer Fehlercode für eine neue Situation

Ändern wir, wie eine Messgröße berechnet wird, sodass sich ihre Zahlen verschieben, sagt das Changelog, welche Messgrößen sich verschieben und um wie viel. Eine solche Änderung kommt zuerst hinter einem Opt-in und wird erst nach der Ankündigungsfrist zum Default.

Wie du es erfährst

Du musst diese Seite nicht noch einmal lesen, um eine Änderung zu bemerken.

1. Die Antwort selbst. Jede erfolgreiche Analyseantwort, einzeln oder als Batch, trägt X-AudioLab-Changelog: https://audiolab.tools/changelog und Link-Header zur Dokumentation, zum OpenAPI-Dokument und zu den Fehlerseiten. Eine Antwort, die einen veralteten Namen enthält, trägt außerdem Deprecation: true, einen Sunset-Header mit dem Datum und einen Link mit rel="deprecation" zum Changelog.
2. Das Changelog. /changelog hat zu jeder Änderung einen Eintrag mit dem Datum.
3. Was ist neu. Die neuesten API-Änderungen stehen oben auf /api und /docs.
4. Dein Konto. Etwa sechs Wochen nach jeder Ankündigung zeigt /account einen Hinweis darauf, was sich geändert hat oder ändern wird und wen es betrifft.

Eine Änderung, die eine funktionierende Integration brechen kann, wird im Changelog, unter „Was ist neu“ und in deinem Konto angekündigt, bevor sie passiert. Betrifft sie ein Feld, sagen es die Antworten, die dieses Feld tragen, in ihren Headern.

Was sich bald ändert

Das Inhaltstyp-Modell wechselt am 15. Januar 2027 auf v2

Der Inhaltstyp einer Datei (contentTypeGuess, mit contentConfidence und contentEvidence) stammt aus einem Modell. Das erste Modell (v1) liefert die API heute. Ein zweites Modell (v2) ist in unseren Tests bei Sprache und Musik deutlich besser (siehe den Status von signal.contentType auf /lenses), und die Website nutzt es bereits. Weil es die Zahlen verschiebt, folgt es der Regel oben: zuerst hinter einem Opt-in, erst nach der Ankündigung der Default.

• Jetzt: Füge einer Anfrage an signallab oder analyze/profile "contentModel": "v2" hinzu (contentModel="v2" als Keyword im Python-Client). Die Antwort hat dieselben Schlüssel und Typen; nur die Werte von Inhaltstyp, Konfidenz und Evidenz unterscheiden sich, und die Evidenzliste enthält model:v2.
• 15. Januar 2027: v2 wird zum Default. "contentModel": "v1" behält das erste Modell mindestens bis zum 15. April 2027.
• Was sich verschiebt: welches Label eine Datei bekommt und mit welcher Konfidenz. mixed ändert seine Bedeutung: v2 sagt mixed, wenn ein Teil der Datei als Sprache und ein Teil als Musik gelesen wird, nicht bei Sprache über Musik (auch das mixed des ersten Modells erkannte das nicht, siehe den Status). Eine Datei unter 3 Sekunden bekommt kein v2-Urteil und behält die Antwort des ersten Modells. noise bedeutet gleichmäßiges Hintergrundrauschen; was weder Stimme noch Musik noch gleichmäßiges Rauschen ist, liest sich als unknown.
• Was sich nicht verschiebt: die Feldnamen und Typen, jede andere Messgröße und die anderen Routen.

Der Sprachdetektor wechselt am 15. Januar 2027 auf K2

Ein Detektor entscheidet, welche Frames einer Aufnahme Sprache sind. Er bestimmt speechRatio, speechSec, silenceSec, longSilences und die segments, und die Messgrößen, die die Pausen lesen, hängen von ihm ab. Der erste Detektor (v1) ist das, was die API heute liefert; er zählt nur die lauteren Teile einer Phrase. Ein zweiter Detektor (K2) lässt eine Phrase in ihre leisen Wortanfänge und -enden auslaufen, um höchstens 100 ms auf jeder Seite. Er war in unseren Tests bei neuen Sprechern besser (Frame-F1 von 0,88 auf 0,94 bei sauberem Audio und bei Rauschen mit 20 und 10 dB, siehe den Status von voice.speechRatio auf /lenses), und die Website nutzt ihn bereits. Er erreicht für diese Messgrößen nicht die ursprüngliche Latte, deshalb ändert keine von ihnen ihren Status. Weil er die Zahlen verschiebt, folgt er der Regel oben: zuerst hinter einem Opt-in, erst nach der Ankündigung der Default.

• Jetzt: Füge einer Anfrage an voicelab/qa, voicelab/segments oder analyze/profile "speechDetector": "k2" hinzu (speechDetector="k2" als Keyword im Python-Client). Die Antwort hat dieselben Schlüssel und Typen; nur die Werte unterscheiden sich.
• 15. Januar 2027: K2 wird zum Default. "speechDetector": "v1" behält den ersten Detektor mindestens bis zum 15. April 2027.
• Was sich verschiebt (durchschnittliche Verschiebung pro Aufnahme an 680 Testmischungen vorgelesener Sprache, je etwa 50 Sekunden, in 17 Rauschbedingungen): speechRatio liest sich 5 bis 14 Punkte höher, speechSec 2,6 bis 6,9 Sekunden höher und silenceSec entsprechend niedriger, longSilences 0,15 bis 0,73 niedriger, und die Segmente sind weniger und länger, weil benachbarte manchmal verschmelzen. Alles, was die Sprach-Frames oder die Pausen liest, verschiebt sich mit, aber weniger (gemessen an 136 dieser Mischungen): averageSpeechRmsDb liest sich bei sauberem Audio 0,5 dB niedriger und bei Rauschen bis zu 1,4 dB niedriger, segmentalSnrDb, segmentalSnrSpreadDb und worstPhraseSnrDb verschieben sich um etwa 1 dB in die eine oder andere Richtung, gapLevelDb liest sich 0,4 bis 2,6 dB niedriger, speechToBackgroundDb bei sauberem Audio 1,3 dB höher und bei Rauschen bis zu 1,4 dB niedriger, die Szenen-Messgrößen verschieben sich um einige Hundertstel, und das Label sceneBackground ändert sich bei etwa 8 Prozent der Mischungen.
• Das Signal-Rausch-Verhältnis wird unter 16 dB korrigiert (SNR-3, einmal getestet an 520 Mischungen von 40 neuen Sprechern in drei Umgebungen, die in keinem früheren Test vorkamen): Mit K2 liest sich signalToNoiseDb bei sauberem Audio und bei 20 dB 0,5 dB niedriger und bei 10, 5 und 0 dB Rauschen etwa 4 bis 5 dB niedriger (durchschnittliche Verschiebung pro Aufnahme an 136 Testmischungen: 4,3, 5,0 und 4,9 dB), weil die alte Messung dort zu hoch lag. Gegenüber dem wahren Verhältnis sank der durchschnittliche Fehler bei 5 dB von +6,0 auf +1,9 dB und bei 10 dB von +3,5 auf -0,2 dB; unter 5 dB liest er sich weiterhin zu hoch (+5,6 dB bei 0 dB). Siehe den Status von voice.snr auf /lenses.
• Aufnahmen mit digitaler Stille zwischen den Phrasen (synthetische Stimmen, etwa die 12 Beispielaufnahmen der Website) verschieben sich deutlich stärker, weil die leisen Ausläufer der Phrasen nicht mehr als Pause zählen: gapLevelDb liest sich 1 bis 15 dB niedriger, speechToBackgroundDb 6 bis 47 dB höher und worstPhraseSnrDb bis zu 31 dB höher. Eine Messgröße, die eine Pause braucht, ist null, wenn kein Pausen-Frame übrig bleibt, was bei 2 der 12 vorkam, und speakingRateLabel änderte sich bei 1 der 12.
• Was sich nicht verschiebt: die Feldnamen und Typen, peakDb, noiseFloorDb, brightness, sibilanceRisk, activeKind, activeVoiceShare, edgeStartDb, edgeEndDb und die anderen Routen.

Was heute veraltet ist

Die niederländischen Feldnamen

Einige Antworten tragen neben dem englischen Namen noch einen niederländischen Feldnamen. Der englische Name trägt denselben Wert, und der niederländische behält seinen alten Wert und seine alte Form bis zum Sunset. Sie bleiben bis zum 31. Januar 2027 (der Sunset-Header sagt Sun, 31 Jan 2027 23:59:59 GMT). Ab dem 1. Februar 2027 stehen nur noch die englischen Namen in den Antworten.

Veralteter Name	Stattdessen verwenden
bron	source
meetVerschil	measurementCaveat
bewijs	sourceUrl
gecontroleerd	verifiedOn
aanvalSterkte	attackStrength
maten	bars
tempoSterkte	tempoStrength
keuzeMarge	candidateMargin
bpmRuw	bpmRaw
octaven	octaveCandidates
naadVerhouding	seamRatio
randStilte	edgeSilence
voorMs	startMs
naMs	endMs
alles	all

Die Explain-Route akzeptiert bis zum selben Datum außerdem vraag neben question.

Von den drei Routen im Vergleich von Voice-Agent- und TTS-Anbietern ist nur mixlab/analyze betroffen: platformNormalisation[] trägt bron und meetVerschil neben source und measurementCaveat. Nichts in diesem Leitfaden liest sie. Die Antworten von voicelab/qa und signallab tragen keinen veralteten Namen.

Zurückgezogene Messgrößen bleiben in der Antwort

Eine Messgröße, deren Behauptung ihren Test nicht bestanden hat, wird als Zurückgezogen markiert, und ihr Feld bleibt in der Antwort, damit nichts bricht. Heute ist das roomEchoScore, das keine Nachhall-Messgröße ist. Sollte ein zurückgezogenes Feld jemals entfernt werden, folgt das der Ankündigung oben.

Mach deine Integration robust

• Lies Felder nach Namen, nie nach Position, und ignoriere Schlüssel, die du nicht kennst.
• Verzweige auf error.code, mit einem Default.
• Logge die Header Deprecation und Sunset, wenn dein Client sie sieht. Sie sind die früheste Warnung.
• Fordere measureStatus an und beobachte die Status der Messgrößen, die du nutzt. Eine Messgröße, die von Proxy auf Validiert wechselt oder umgekehrt, zeigt es dort zuerst.
• Halte einen kleinen eigenen Test bereit: Ruf die drei Routen mit einer kurzen Datei auf und vergleiche die Feldnamen und Typen mit dem, was du heute liest.

Letzte Änderungen

• 20 October 2026. The chain profile now also returns the echo and slapback measure. Eintrag lesen.
• 13 October 2026. Three new profiles: room (reverberation from a clap), chain (lost packets) and pitch (where a voice sits and how clean it is). Eintrag lesen.
• 13 October 2026. A new speech detector: try it with "speechDetector": "k2" now, it becomes the default on 15 January 2027. Eintrag lesen.
• 13 October 2026. A new content-type model: try it with "contentModel": "v2" now, it becomes the default on 15 January 2027. Eintrag lesen.
• 12 October 2026. GET /v1/usage, a Python client, ready calls in the spec, a reference you can try, and two new guides. Eintrag lesen.
• 12 October 2026. Errors have codes and links, two opt-in options, and the Dutch field names stay until 31 January 2027. Eintrag lesen.

Fragen

Schreib an support@audiolab.tools und nenne, worauf du aufbaust und welche Route du aufrufst. Wenn dich eine Änderung treffen würde, sag es vor dem Datum in der Ankündigung.