API text to speech français : le premier appel, de bout en bout
Pour un développeur qui veut sonoriser un article depuis son propre code, voici l'appel minimal et la réponse qu'il renvoie, tirés de la documentation publique. Un texte, une requête, un audio, et ce qu'il faut savoir avant de brancher un CMS entier.
Si vous avez un CMS maison, ou que vous voulez sonoriser vos articles sans passer par une extension, l'API est le chemin direct : vous envoyez un texte, vous recevez un audio. Avant de brancher tout un site, il est utile de voir à quoi ressemble un seul appel, ce qu'il renvoie, et les quelques règles qui vous éviteront de perdre une heure. Cet article montre l'appel minimal, tel qu'il figure dans la documentation publique, reproductible en l'état.
Un appel, trois lignes qui comptent
Chaque requête porte une clé, transmise en en-tête. C'est une clé par site, elle commence par wd_live_, et aucune route n'est servie sans elle (sauf le catalogue de voix). La route principale est une requête POST vers /api/v1/podcasts. Voici l'appel minimal :
```
POST https://wedispatch.fr/api/v1/podcasts
Authorization: Bearer wd_live_xxxxxxxxxxxxxxxx
Content-Type: application/json
{
"text": "Le conseil municipal a adopte hier soir le budget 2027.",
"title": "Le budget 2027 adopte",
"wait": true
}
```
Trois champs suffisent. Le text est le seul obligatoire : il va de 100 à 100 000 caractères. Le title sert au flux podcast et à la page de provenance. Le wait à vrai demande à la réponse d'attendre la fin de la synthèse et d'y mettre l'adresse du fichier : l'article se publie déjà sonorisé, sans délai visible côté intégrateur.
La réponse, et ce qu'on en fait
Avec wait à vrai, la réponse contient de quoi afficher l'audio immédiatement : un article_id, un job_id, un status, un embed, puis l'audio_url, la duration_s, la version, le engine, la voice et un indicateur fallback. Vous branchez votre lecteur sur l'audio_url et vous avez terminé. Sans wait, la réponse revient tout de suite avec le status en cours de traitement, et c'est à vous de repasser plus tard, ou de fournir un webhook_url dans l'appel pour être prévenu quand le fichier est prêt.
Une précision qui évite une mauvaise surprise : le mode synchrone (wait) n'a plus d'effet au-delà de 20 000 caractères. Un article long se produit forcément en arrière-plan, et il faut prévoir le webhook ou la relecture d'état plutôt que d'attendre l'audio dans la réponse.
Les erreurs qu'il faut savoir traiter
Trois codes reviennent, et c'est sur le code HTTP qu'il faut brancher votre logique, jamais sur le texte du message (qui peut être en français ou en anglais selon l'en-tête Accept-Language). Un 400 signale un texte, une voix, une langue ou une date invalides. Un 403 signale un compte bloqué. Un 429 signale soit le quota mensuel atteint, soit la limite de dix générations par minute dépassée. Traitez ces trois cas et votre intégration tient la route.
Deux garde-fous valent la peine d'être connus. Le champ external_id, votre propre identifiant d'article, garantit la déduplication : le même envoyé deux fois ne produit qu'un seul audio. Et l'en-tête Idempotency-Key fait la même promesse au niveau de la requête : rejouer le même appel avec la même clé ne facture pas un second audio. Ce sont les deux filets qui évitent de payer deux fois une reprise réseau.
Ce que l'appel coûte, et ce qu'il faut savoir avant de brancher tout un site
Le prix se compte au caractère : un crédit couvre mille caractères, et un article consomme un crédit par tranche de mille entamée (la tranche entamée est perdue). Un article de 3 000 caractères coûte donc trois crédits. C'est la même règle pour une régénération qu'une création : il n'y a pas de budget de retouche gratuit à récupérer, et régénérer un article pour « récupérer » quelque chose ne récupère rien. La documentation publique de l'API donne le détail route par route, et elle a été écrite après un audit : elle ne décrit que ce qui existe vraiment.
Avant de câbler un CMS entier, deux conseils. D'abord, testez un article seul, vérifiez la prononciation de vos sigles et noms propres, et seulement ensuite passez au lot : la route de génération par lot accepte jusqu'à vingt-cinq articles par requête, pratique pour un fonds d'archives. Ensuite, décidez qui déclenche : un champ trigger à auto soumet l'article à l'interrupteur de sonorisation automatique du compte, un trigger à manual force la production. Toute l'architecture d'une intégration maison est détaillée dans notre guide sur l'audio par API pour un CMS maison.
API, extension ou pilotage par agent
L'API n'est pas le seul chemin, et ce n'est pas toujours le plus court. Si votre site tourne sous WordPress, l'extension fait le même travail sans que vous manipuliez de clé : tout est détaillé sur notre page WordPress et API. Et si vous orchestrez déjà vos publications avec des agents, le pilotage de la sonorisation par agents IA expose ces mêmes routes autrement. L'API reste la bonne réponse quand vous avez un CMS maison ou un besoin sur mesure : un appel, un audio, et le contrôle complet du moment où ça se déclenche.
Sonorisez vos articles avec WeDispatch
Ce blog sera lui-même sonorisé par WeDispatch. Envie de voir ce que ça donne sur vos contenus ?
Demandez une démo