Wijzigingen en deprecation: wat er verandert, wanneer, en hoe je het te weten komt

Als je op de API bouwt, is deze pagina het vaste adres voor één vraag: wat kan er onder me veranderen, en hoe weet ik dat? Het adres verhuist niet.

De belofte

Vandaag heeft de API één versie, /v1. Daarbinnen geldt:

• Niets wordt zonder aankondiging verwijderd, hernoemd of van type veranderd. Een veld dat je vandaag leest, houdt zijn naam, zijn type en zijn betekenis.
• Nieuwe velden komen achter een opt-in. Een antwoord dat je al parset, krijgt geen sleutel erbij waar je niet om vroeg: round en measureStatus zijn de eerste twee opt-ins, en zonder die zijn je antwoorden byte voor byte wat ze waren. Als een veld ooit in het standaardantwoord moet verschijnen, wordt het eerst in de changelog aangekondigd en komt het als één nieuwe sleutel, nooit binnen een bestaand object.
• Foutcodes behouden hun betekenis. Een nieuwe situatie kan een nieuwe code krijgen, dus vertak op error.code en houd een standaardpad voor codes die je niet kent. Vertak nooit op de formulering van message.

Wat telt als een wijziging

Gebeurt op elk moment	Eerst aangekondigd, met minstens 90 dagen
Een nieuwe route	Een veld verwijderen of hernoemen
Een nieuwe opt-in-optie	Het type, de eenheid of de betekenis van een veld wijzigen
Een nieuwe status, marge of uitleg in de documentatie	Een route of een optie verwijderen
Een snellere analyse met dezelfde getallen	Een regel die eerder niet werd afgedwongen, wordt afgedwongen
Een nieuwe foutcode voor een nieuwe situatie

Als we veranderen hoe een maat wordt berekend, zodat zijn getallen verschuiven, zegt de changelog welke maten verschuiven en met hoeveel. Zo’n wijziging komt eerst achter een opt-in en wordt pas na de aankondigingstermijn de standaard.

Hoe je het te weten komt

Je hoeft deze pagina niet opnieuw te lezen om een wijziging op te merken.

1. De respons zelf. Elke geslaagde analyserespons, enkel of batch, draagt X-AudioLab-Changelog: https://audiolab.tools/changelog en Link-headers naar de documentatie, het OpenAPI-document en de foutpagina’s. Een respons die een deprecated naam bevat, draagt ook Deprecation: true, een Sunset-header met de datum en een Link met rel="deprecation" naar de changelog.
2. De changelog. /changelog heeft voor elke wijziging een vermelding, met de datum.
3. What’s new. De laatste API-wijzigingen staan bovenaan /api en /docs.
4. Je account. Ongeveer zes weken na elke aankondiging toont /account een melding met wat er is veranderd of gaat veranderen, en wie het raakt.

Een wijziging die een werkende integratie kan breken, wordt in de changelog, in What’s new en in je account aangekondigd voordat ze gebeurt. Als ze een veld raakt, zeggen de responses die dat veld dragen het in hun headers.

Wat er gaat veranderen

Het contenttypemodel gaat op 15 januari 2027 naar v2

Het contenttype van een bestand (contentTypeGuess, met contentConfidence en contentEvidence) komt uit een model. Het eerste model (v1) is wat de API vandaag teruggeeft. Een tweede model (v2) is in onze toetsen veel beter op spraak en muziek (zie de status van signal.contentType op /lenses), en de website gebruikt het al. Omdat het de getallen verschuift, volgt het de regel hierboven: eerst achter een opt-in, pas na de aankondiging de standaard.

• Nu: voeg "contentModel": "v2" toe aan een verzoek naar signallab of analyze/profile (contentModel="v2" als keyword in de Python-client). Het antwoord heeft dezelfde sleutels en types; alleen de waarden van het contenttype, zijn zekerheid en zijn evidence verschillen, en de evidencelijst bevat model:v2.
• 15 januari 2027: v2 wordt de standaard. "contentModel": "v1" behoudt het eerste model tot minstens 15 april 2027.
• Wat verschuift: welk label een bestand krijgt, en met welke zekerheid. mixed verandert van betekenis: v2 zegt mixed als een deel van het bestand als spraak leest en een deel als muziek, niet voor spraak over muziek (het mixed van het eerste model detecteerde dat ook niet, zie de status). Een bestand korter dan 3 seconden krijgt geen v2-oordeel en behoudt het antwoord van het eerste model. noise betekent stationaire achtergrondruis; wat geen van stem, muziek of stationaire ruis is, leest unknown.
• Wat niet verschuift: de veldnamen en types, elke andere maat, en de andere routes.

De spraakdetector gaat op 15 januari 2027 naar K2

Een detector bepaalt welke frames van een opname spraak zijn. Hij bepaalt speechRatio, speechSec, silenceSec, longSilences en de segments, en de maten die de pauzes lezen hangen ervan af. De eerste detector (v1) is wat de API vandaag teruggeeft; hij telt alleen de luidere delen van een frase mee. Een tweede detector (K2) laat een frase doorlopen in zijn zachte woordaanzetten en -uitgangen, met hoogstens 100 ms aan elke kant. Hij was in onze toetsen beter op nieuwe sprekers (frame-F1 van 0,88 naar 0,94 op schone audio en ruis op 20 en 10 dB, zie de status van voice.speechRatio op /lenses), en de website gebruikt hem al. Hij haalt de oorspronkelijke lat voor deze maten niet, dus geen van die maten verandert van status. Omdat hij de getallen verschuift, volgt hij de regel hierboven: eerst achter een opt-in, pas na de aankondiging de standaard.

• Nu: voeg "speechDetector": "k2" toe aan een verzoek naar voicelab/qa, voicelab/segments of analyze/profile (speechDetector="k2" als keyword in de Python-client). Het antwoord heeft dezelfde sleutels en types; alleen de waarden verschillen.
• 15 januari 2027: K2 wordt de standaard. "speechDetector": "v1" behoudt de eerste detector tot minstens 15 april 2027.
• Wat verschuift (gemiddelde verschuiving per opname op 680 testmengsels van voorgelezen spraak, ongeveer 50 seconden elk, in 17 ruiscondities): speechRatio leest 5 tot 14 punten hoger, speechSec 2,6 tot 6,9 seconden hoger en silenceSec evenveel lager, longSilences 0,15 tot 0,73 lager, en de segmenten zijn minder en langer, omdat naburige soms samensmelten. Alles wat de spraakframes of de pauzes leest, verschuift mee, met minder (gemeten op 136 van die mengsels): averageSpeechRmsDb leest 0,5 dB lager op schone audio en tot 1,4 dB lager in ruis, segmentalSnrDb, segmentalSnrSpreadDb en worstPhraseSnrDb verschuiven ongeveer 1 dB naar beide kanten, gapLevelDb leest 0,4 tot 2,6 dB lager, speechToBackgroundDb 1,3 dB hoger op schone audio en tot 1,4 dB lager in ruis, de scenemaaten verschuiven een paar honderdsten, en het label sceneBackground verandert bij ongeveer 8 procent van de mengsels.
• De signaal-ruisverhouding wordt onder 16 dB gecorrigeerd (SNR-3, eenmalig getoetst op 520 mengsels van 40 nieuwe sprekers in drie omgevingen die in geen eerdere toets zaten): met K2 leest signalToNoiseDb 0,5 dB lager op schone audio en op 20 dB, en ongeveer 4 tot 5 dB lager bij ruis van 10, 5 en 0 dB (gemiddelde verschuiving per opname op 136 testmengsels: 4,3, 5,0 en 4,9 dB), omdat de oude waarde daar te hoog was. Tegen de ware verhouding ging de gemiddelde fout op 5 dB van +6,0 naar +1,9 dB en op 10 dB van +3,5 naar -0,2 dB; onder 5 dB leest hij nog steeds te hoog (+5,6 dB op 0 dB). Zie de status van voice.snr op /lenses.
• Opnames met digitale stilte tussen de frasen (synthetische stemmen, zoals de 12 voorbeeldopnames van de site) verschuiven veel meer, omdat de zachte staarten van de frasen niet langer als pauze tellen: gapLevelDb leest 1 tot 15 dB lager, speechToBackgroundDb 6 tot 47 dB hoger en worstPhraseSnrDb tot 31 dB hoger. Een maat die een pauze nodig heeft, is null als er geen pauzeframe over is, wat bij 2 van de 12 gebeurde, en speakingRateLabel veranderde bij 1 van de 12.
• Wat niet verschuift: de veldnamen en types, peakDb, noiseFloorDb, brightness, sibilanceRisk, activeKind, activeVoiceShare, edgeStartDb, edgeEndDb, en de andere routes.

Wat vandaag deprecated is

De Nederlandse veldnamen

Sommige antwoorden dragen nog een Nederlandse veldnaam naast de Engelse. De Engelse naam draagt dezelfde waarde, en de Nederlandse houdt zijn oude waarde en vorm tot de sunset. Ze blijven tot 31 januari 2027 (de Sunset-header zegt Sun, 31 Jan 2027 23:59:59 GMT). Vanaf 1 februari 2027 staan alleen de Engelse namen in de antwoorden.

Deprecated naam	Gebruik in plaats daarvan
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

De explain-route accepteert tot dezelfde datum ook vraag naast question.

Van de drie routes in Voice-agent- en TTS-vendors vergelijken is alleen mixlab/analyze geraakt: platformNormalisation[] draagt bron en meetVerschil naast source en measurementCaveat. Niets in die gids leest ze. De responses van voicelab/qa en signallab dragen geen deprecated naam.

Ingetrokken maten blijven in het antwoord

Een maat waarvan de claim zijn toets faalde, wordt Ingetrokken genoemd, en zijn veld blijft in het antwoord zodat niets breekt. Vandaag is dat roomEchoScore, dat geen galmmaat is. Als een ingetrokken veld ooit wordt verwijderd, volgt dat de aankondiging hierboven.

Maak je integratie moeilijk te breken

• Lees velden op naam, nooit op positie, en negeer sleutels die je niet kent.
• Vertak op error.code, met een standaardpad.
• Log de Deprecation- en Sunset-headers als je client ze ziet. Het is de vroegste waarschuwing.
• Vraag measureStatus aan en let op de statussen van de maten die je gebruikt. Een maat die van Proxy naar Gevalideerd gaat, of andersom, laat dat daar het eerst zien.
• Houd een kleine eigen toets bij: roep de drie routes aan met een kort bestand en vergelijk de veldnamen en types met wat je vandaag leest.

Recente wijzigingen

• 20 October 2026. The chain profile now also returns the echo and slapback measure. Lees de vermelding.
• 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). Lees de vermelding.
• 13 October 2026. A new speech detector: try it with "speechDetector": "k2" now, it becomes the default on 15 January 2027. Lees de vermelding.
• 13 October 2026. A new content-type model: try it with "contentModel": "v2" now, it becomes the default on 15 January 2027. Lees de vermelding.
• 12 October 2026. GET /v1/usage, a Python client, ready calls in the spec, a reference you can try, and two new guides. Lees de vermelding.
• 12 October 2026. Errors have codes and links, two opt-in options, and the Dutch field names stay until 31 January 2027. Lees de vermelding.

Vragen

Schrijf naar support@audiolab.tools met waarop je bouwt en welke route je aanroept. Als een wijziging je zou schaden, zeg dat dan voor de datum in de aankondiging.