Changements et dépréciation : ce qui change, quand, et comment vous le savez

Si vous construisez sur l’API, cette page est l’adresse fixe pour une seule question : qu’est-ce qui peut changer sous mes pieds, et comment le saurai-je ? L’adresse ne bougera pas.

La promesse

Aujourd’hui l’API n’a qu’une version, /v1. À l’intérieur de celle-ci :

• Rien n’est supprimé, renommé ou retypé sans préavis. Un champ que vous lisez aujourd’hui garde son nom, son type et son sens.
• Les nouveaux champs arrivent derrière une option à activer. Une réponse que vous analysez déjà ne gagne pas de clé que vous n’avez pas demandée : round et measureStatus sont les deux premières options, et sans elles vos réponses sont octet pour octet ce qu’elles étaient. Si un champ doit un jour apparaître dans la réponse par défaut, il est annoncé d’abord dans le changelog et arrive sous la forme d’une seule nouvelle clé, jamais à l’intérieur d’un objet existant.
• Les codes d’erreur gardent leur sens. Une nouvelle situation peut recevoir un nouveau code : branchez donc sur error.code et gardez un cas par défaut pour les codes que vous ne connaissez pas. Ne branchez jamais sur le libellé de message.

Ce qui compte comme un changement

Arrive à tout moment	Annoncé d’abord, avec au moins 90 jours
Une nouvelle route	Supprimer ou renommer un champ
Une nouvelle option à activer	Changer le type, l’unité ou le sens d’un champ
Un nouveau statut, une nouvelle marge ou une nouvelle explication dans la documentation	Supprimer une route ou une option
Une analyse plus rapide avec les mêmes chiffres	Une règle qui n’était pas appliquée jusque-là commence à l’être
Un nouveau code d’erreur pour une nouvelle situation

Quand nous changeons le calcul d’une mesure, de sorte que ses chiffres bougent, le changelog dit quelles mesures bougent et de combien. Un tel changement arrive d’abord derrière une option à activer et ne devient la valeur par défaut qu’après le délai de préavis.

Comment vous le savez

Vous n’avez pas besoin de relire cette page pour remarquer un changement.

1. La réponse elle-même. Chaque réponse d’analyse réussie, unitaire ou par lot, porte X-AudioLab-Changelog: https://audiolab.tools/changelog et des en-têtes Link vers la documentation, le document OpenAPI et les pages d’erreurs. Une réponse qui contient un nom déprécié porte aussi Deprecation: true, un en-tête Sunset avec la date, et un Link avec rel="deprecation" vers le changelog.
2. Le changelog. /changelog a une entrée pour chaque changement, avec la date.
3. Nouveautés. Les derniers changements de l’API figurent en haut de /api et de /docs.
4. Votre compte. Pendant environ six semaines après chaque annonce, /account affiche un avis qui dit ce qui a changé ou va changer, et qui est concerné.

Un changement qui peut casser une intégration qui fonctionne est annoncé dans le changelog, dans les nouveautés et dans votre compte avant qu’il n’arrive. Quand il touche un champ, les réponses qui portent ce champ le disent dans leurs en-têtes.

Ce qui est sur le point de changer

Le modèle de type de contenu passe à la v2 le 15 janvier 2027

Le type de contenu d’un fichier (contentTypeGuess, avec contentConfidence et contentEvidence) vient d’un modèle. Le premier modèle (v1) est ce que l’API renvoie aujourd’hui. Un second modèle (v2) est nettement meilleur sur la parole et la musique dans nos tests (voir le statut de signal.contentType sur /lenses), et le site web l’utilise déjà. Comme il déplace les chiffres, il suit la règle ci-dessus : d’abord derrière une option à activer, par défaut seulement après le préavis.

• Maintenant : ajoutez "contentModel": "v2" à une requête vers signallab ou analyze/profile (contentModel="v2" comme argument nommé dans le client Python). La réponse a les mêmes clés et les mêmes types ; seules les valeurs du type de contenu, de sa confiance et de ses indices diffèrent, et la liste des indices contient model:v2.
• 15 janvier 2027 : la v2 devient la valeur par défaut. "contentModel": "v1" conserve le premier modèle jusqu’au 15 avril 2027 au moins.
• Ce qui bouge : l’étiquette qu’un fichier reçoit, et avec quelle confiance. mixed change de sens : la v2 dit mixed quand une partie du fichier se lit comme de la parole et une partie comme de la musique, pas pour de la parole sur de la musique (le mixed du premier modèle ne détectait pas cela non plus, voir le statut). Un fichier de moins de 3 secondes ne reçoit pas de verdict v2 et garde la réponse du premier modèle. noise désigne un bruit de fond stationnaire ; ce qui n’est ni voix, ni musique, ni bruit stationnaire se lit unknown.
• Ce qui ne bouge pas : les noms et les types des champs, toutes les autres mesures, et les autres routes.

Le détecteur de parole passe à K2 le 15 janvier 2027

Un détecteur décide quelles trames d’un enregistrement sont de la parole. Il fixe speechRatio, speechSec, silenceSec, longSilences et les segments, et les mesures qui lisent les pauses en dépendent. Le premier détecteur (v1) est ce que l’API renvoie aujourd’hui ; il ne compte que les parties les plus fortes d’une phrase. Un second détecteur (K2) laisse une phrase se prolonger dans ses débuts et ses fins de mots plus faibles, d’au plus 100 ms de chaque côté. Il était meilleur sur de nouveaux locuteurs dans nos tests (F1 par trame de 0,88 à 0,94 sur de l’audio propre et avec bruit à 20 et 10 dB, voir le statut de voice.speechRatio sur /lenses), et le site web l’utilise déjà. Il n’atteint pas le seuil d’origine pour ces mesures, donc aucune d’elles ne change de statut. Comme il déplace les chiffres, il suit la règle ci-dessus : d’abord derrière une option à activer, par défaut seulement après le préavis.

• Maintenant : ajoutez "speechDetector": "k2" à une requête vers voicelab/qa, voicelab/segments ou analyze/profile (speechDetector="k2" comme argument nommé dans le client Python). La réponse a les mêmes clés et les mêmes types ; seules les valeurs diffèrent.
• 15 janvier 2027 : K2 devient la valeur par défaut. "speechDetector": "v1" conserve le premier détecteur jusqu’au 15 avril 2027 au moins.
• Ce qui bouge (décalage moyen par enregistrement sur 680 mélanges de test de parole lue, d’environ 50 secondes chacun, dans 17 conditions de bruit) : speechRatio se lit de 5 à 14 points plus haut, speechSec de 2,6 à 6,9 secondes plus haut et silenceSec d’autant plus bas, longSilences de 0,15 à 0,73 plus bas, et les segments sont moins nombreux et plus longs, parce que des segments voisins fusionnent parfois. Tout ce qui lit les trames de parole ou les pauses bouge avec eux, moins fortement (mesuré sur 136 de ces mélanges) : averageSpeechRmsDb se lit 0,5 dB plus bas sur de l’audio propre et jusqu’à 1,4 dB plus bas dans le bruit, segmentalSnrDb, segmentalSnrSpreadDb et worstPhraseSnrDb bougent d’environ 1 dB dans un sens ou dans l’autre, gapLevelDb se lit de 0,4 à 2,6 dB plus bas, speechToBackgroundDb 1,3 dB plus haut sur de l’audio propre et jusqu’à 1,4 dB plus bas dans le bruit, les mesures de scène bougent de quelques centièmes, et l’étiquette sceneBackground change pour environ 8 pour cent des mélanges.
• Le rapport signal sur bruit est corrigé en dessous de 16 dB (SNR-3, testé une fois sur 520 mélanges de 40 nouveaux locuteurs dans trois environnements qui ne figuraient dans aucun test antérieur) : avec K2, signalToNoiseDb se lit 0,5 dB plus bas sur de l’audio propre et à 20 dB, et d’environ 4 à 5 dB plus bas avec un bruit à 10, 5 et 0 dB (décalage moyen par enregistrement sur 136 mélanges de test : 4,3, 5,0 et 4,9 dB), parce que l’ancienne lecture était trop haute à ces niveaux. Par rapport au vrai rapport, l’erreur moyenne à 5 dB est passée de +6,0 à +1,9 dB et à 10 dB de +3,5 à -0,2 dB ; en dessous de 5 dB, il se lit encore trop haut (+5,6 dB à 0 dB). Voir le statut de voice.snr sur /lenses.
• Les enregistrements avec du silence numérique entre les phrases (voix synthétiques, comme les 12 enregistrements d’exemple du site) bougent beaucoup plus, parce que les queues faibles des phrases ne comptent plus comme pause : gapLevelDb se lit de 1 à 15 dB plus bas, speechToBackgroundDb de 6 à 47 dB plus haut et worstPhraseSnrDb jusqu’à 31 dB plus haut. Une mesure qui a besoin d’une pause vaut null quand il ne reste aucune trame de pause, ce qui est arrivé pour 2 des 12, et speakingRateLabel a changé pour 1 des 12.
• Ce qui ne bouge pas : les noms et les types des champs, peakDb, noiseFloorDb, brightness, sibilanceRisk, activeKind, activeVoiceShare, edgeStartDb, edgeEndDb, et les autres routes.

Ce qui est déprécié aujourd’hui

Les noms de champs néerlandais

Certaines réponses portent encore un nom de champ néerlandais à côté du nom anglais. Le nom anglais porte la même valeur, et le néerlandais garde son ancienne valeur et sa forme jusqu’à la date d’arrêt (le sunset). Ils restent jusqu’au 31 janvier 2027 (l’en-tête Sunset dit Sun, 31 Jan 2027 23:59:59 GMT). À partir du 1er février 2027, seuls les noms anglais figurent dans les réponses.

Nom déprécié	À utiliser à la place
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

La route d’explication accepte aussi vraag à côté de question jusqu’à la même date.

Parmi les trois routes de Comparer les fournisseurs d’agents vocaux et de synthèse vocale, seule mixlab/analyze est concernée : platformNormalisation[] porte bron et meetVerschil à côté de source et measurementCaveat. Rien dans ce guide ne les lit. Les réponses de voicelab/qa et de signallab ne portent aucun nom déprécié.

Les mesures retirées restent dans la réponse

Une mesure dont l’affirmation a échoué à son test est marquée Retiré, et son champ reste dans la réponse pour que rien ne casse. Aujourd’hui, c’est roomEchoScore, qui n’est pas une mesure de réverbération. Si un champ retiré est un jour supprimé, il suit le préavis ci-dessus.

Rendez votre intégration difficile à casser

• Lisez les champs par leur nom, jamais par leur position, et ignorez les clés que vous ne connaissez pas.
• Branchez sur error.code, avec un cas par défaut.
• Journalisez les en-têtes Deprecation et Sunset si votre client les voit. C’est l’avertissement le plus précoce.
• Demandez measureStatus et surveillez les statuts des mesures que vous utilisez. Une mesure qui passe de Proxy à Validé, ou l’inverse, s’y montre en premier.
• Gardez un petit test à vous : appelez les trois routes avec un court fichier et comparez les noms et les types des champs avec ce que vous lisez aujourd’hui.

Changements récents

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

Questions

Écrivez à support@audiolab.tools en disant sur quoi vous construisez et quelle route vous appelez. Si un changement vous porterait préjudice, dites-le avant la date du préavis.