French text-to-speech API: the first call, end to end

If you run a homegrown CMS, or you want to narrate your articles without a plugin, the API is the direct route: you send a text, you get back an audio file. Before wiring up a whole site, it helps to see what a single call looks like, what it returns, and the few rules that will save you an hour. This article shows the minimal call, exactly as it appears in the public documentation, reproducible as is.

One call, three lines that matter

Every request carries a key, sent as a header. It is one key per site, it starts with wd_live_, and no route is served without it (except the voice catalogue). The main route is a POST request to /api/v1/podcasts. Here is the minimal call:

```
POST https://wedispatch.fr/api/v1/podcasts
Authorization: Bearer wd_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
"text": "The city council approved the 2027 budget last night.",
"title": "2027 budget approved",
"wait": true
}
```

Three fields are enough. The text is the only required one: it runs from 100 to 100,000 characters. The title feeds the podcast feed and the provenance page. Setting wait to true asks the response to wait for synthesis to finish and to include the file's address: the article publishes already narrated, with no visible delay on the integrator's side.

The response, and what you do with it

With wait set to true, the response carries everything you need to show the audio at once: an article_id, a job_id, a status, an embed, then the audio_url, the duration_s, the version, the engine, the voice, and a fallback flag. You point your player at the audio_url and you are done. Without wait, the response comes straight back with the status still processing, and it is up to you to poll later, or to pass a webhook_url in the call to be told when the file is ready.

One detail that avoids a nasty surprise: synchronous mode (wait) no longer has any effect beyond 20,000 characters. A long article is necessarily produced in the background, so plan for the webhook or a status poll rather than expecting the audio in the response.

The errors you must handle

Three codes come up, and it is the HTTP code you should branch your logic on, never the message text (which may be French or English depending on the Accept-Language header). A 400 flags an invalid text, voice, language or date. A 403 flags a blocked account. A 429 flags either the monthly quota reached or the ten-generations-per-minute limit exceeded. Handle those three cases and your integration holds up.

Two guardrails are worth knowing. The external_id field, your own article identifier, guarantees deduplication: the same one sent twice produces a single audio. And the Idempotency-Key header makes the same promise at the request level: replaying the same call with the same key does not bill a second audio. These are the two nets that stop you paying twice for a network retry.

What the call costs, and what to know before wiring a whole site

Pricing is counted per character: one credit covers a thousand characters, and an article consumes one credit per started block of a thousand (the started block is not refunded). A 3,000-character article therefore costs three credits. The rule is the same for a regeneration as for a creation: there is no free correction budget to recover, and regenerating an article to "get back" something recovers nothing. The public API documentation gives the route-by-route detail, and it was written after an audit: it describes only what actually exists.

Before cabling a whole CMS, two tips. First, test a single article, check the pronunciation of your acronyms and proper nouns, and only then move to the batch: the batch generation route accepts up to twenty-five articles per request, handy for an archive. Second, decide who triggers: a trigger field set to auto submits the article to the account's automatic-narration switch, a trigger set to manual forces production. The full shape of a homegrown integration is laid out in our guide to audio via API for any CMS.

API, plugin, or agent-driven

The API is not the only route, and it is not always the shortest. If your site runs on WordPress, the plugin does the same job without you touching a key: it is all set out on our WordPress and API page. And if you already orchestrate your publishing with agents, driving narration with AI agents exposes these same routes another way. The API stays the right answer when you have a homegrown CMS or a bespoke need: one call, one audio, and full control over when it fires.

Read next

• Synthetic voices and emotion: what they convey, and what they don't act out
• Audio for magazines: what the long form changes
• Turn your feed into a podcast on Apple, Spotify and Deezer: what each one requires