Guides
API de synthèse vocale : guide avec exemples Python et JS
L'équipe Voizum · Mis à jour · 12 min de lecture
Une API de synthèse vocale transforme un texte en fichier audio depuis votre propre code ou une automatisation, sans que personne ne clique sur un bouton. Ce guide explique comment en choisir une selon votre usage, puis déroule une intégration complète qui fonctionne : créer la tâche, vérifier son état, télécharger le MP3. Il couvre aussi les textes longs, les lots, l'utilisation de votre propre voix clonée et le branchement sur n8n, Make ou Zapier.
L'API consomme les crédits d'un pack (60 par tranche de 1 000 caractères). Packs à partir de 5,99 €, sans abonnement.
À quoi sert une API de synthèse vocale et quand en a-t-on besoin ?
Une API TTS (text to speech) est un point d'accès HTTP : vous envoyez un texte et une voix, et vous recevez un audio. Elle devient utile dès que l'audio fait partie d'un processus et non d'une tâche ponctuelle. Si vous commentez une vidéo par mois, un éditeur web est plus rapide. Si vous en commentez une par jour, ou si votre produit doit parler, une API vous évite à chaque fois le cycle copier, coller, télécharger.
Là où nous la voyons le plus utilisée :
- YouTube et chaînes sans visage : le script sort d'une étape d'écriture (souvent un modèle d'IA) et passe directement à la voix off, puis au logiciel de montage.
- E-learning et formations : des centaines de leçons courtes régénérées à chaque modification du texte.
- Applications et produits : notifications, onboarding, accessibilité, boutons « écouter l'article ».
- Lots : fiches produit, versions audio d'un blog, serveurs vocaux, versions multilingues d'un même script.
- Automatisations sans code : des scénarios n8n, Make ou Zapier qui transforment une nouvelle ligne d'un tableur en MP3.
Récupérer votre clé et votre voice_id
Tout passe par du REST simple avec du JSON, l'URL de base https://voizum.com/api/v1 et une authentification par clé Bearer qui commence par sk_voizum_. Le déroulement est toujours le même : créer une tâche, vérifier son état, télécharger le MP3.
- 1Achetez n'importe quel pack de crédits sur Voizum : cela débloque la clé d'API. L'API consomme les crédits achetés, jamais les crédits gratuits du mois.
- 2Ouvrez la page API et générez votre clé. Elle n'est affichée qu'une fois : stockez-la tout de suite dans une variable d'environnement (VOIZUM_API_KEY) ou dans votre gestionnaire de secrets.
- 3Ajoutez une voix à votre bibliothèque : clonez la vôtre ou enregistrez-en une de la bibliothèque publique avec Ajouter. L'API ne fonctionne qu'avec les voix de votre bibliothèque.
- 4Listez-les avec GET /voices. Chaque élément a un id, un nom et une langue ; l'id est le voice_id que vous envoyez à la génération. Vous pouvez aussi le copier sur le site : Voix, menu ⋯, ID API.
- 5Facultatif : avant une grosse série, GET /status (public, sans clé) indique que le service fonctionne, et GET /account affiche votre solde de crédits et vos limites.
Exemples de code : curl, Python et JavaScript
Les exemples ci-dessous fonctionnent tels quels une fois YOUR_VOICE_ID et JOB_ID remplacés. L'URL de l'audio renvoyée par la consultation de l'état demande le même en-tête Authorization et redirige vers le fichier : laissez donc votre client HTTP suivre les redirections.
curl
Créez la tâche (202 avec job_id et eta_seconds), interrogez-la, puis téléchargez :
# 1. Créer la tâche
curl -X POST https://voizum.com/api/v1/tts \
-H "Authorization: Bearer $VOIZUM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: video-042-intro" \
-d '{"text": "Bienvenue sur la chaîne.", "voice_id": "YOUR_VOICE_ID"}'
# 2. Vérifier son état (répéter jusqu'à "done")
curl https://voizum.com/api/v1/tts/JOB_ID -H "Authorization: Bearer $VOIZUM_API_KEY"
# 3. Télécharger le MP3
curl -L -o narration.mp3 https://voizum.com/api/v1/tts/JOB_ID/audio -H "Authorization: Bearer $VOIZUM_API_KEY"Python (requests)
Le même déroulement, avec une attente tant que la tâche est en file ou en cours :
import os, time, requests
API = "https://voizum.com/api/v1"
H = {"Authorization": "Bearer " + os.environ["VOIZUM_API_KEY"]}
# 1. Créer la tâche
with open("script.txt", encoding="utf-8") as f:
texto = f.read()
r = requests.post(API + "/tts", headers=H, json={"text": texto, "voice_id": "YOUR_VOICE_ID"})
r.raise_for_status()
job = r.json()["job_id"]
# 2. Attendre tant qu'elle est en file ou en cours
while True:
s = requests.get(API + "/tts/" + job, headers=H).json()
if s["status"] not in ("queued", "processing"):
break
time.sleep(5)
if s["status"] != "done":
raise RuntimeError(s.get("error", s["status"]))
# 3. Télécharger le MP3
audio = requests.get(s["audio_url"], headers=H)
audio.raise_for_status()
with open("narration.mp3", "wb") as f:
f.write(audio.content)JavaScript (Node 18+, modules ES)
fetch natif, sans SDK :
import fs from "node:fs";
const API = "https://voizum.com/api/v1";
const H = { Authorization: "Bearer " + process.env.VOIZUM_API_KEY, "Content-Type": "application/json" };
// 1. Créer la tâche
const crear = await fetch(API + "/tts", {
method: "POST",
headers: H,
body: JSON.stringify({ text: "Bienvenue sur la chaîne.", voice_id: "YOUR_VOICE_ID" }),
});
if (!crear.ok) throw new Error(await crear.text());
const { job_id } = await crear.json();
// 2. Attendre tant qu'elle est en file ou en cours
let s;
do {
await new Promise((r) => setTimeout(r, 5000));
s = await (await fetch(API + "/tts/" + job_id, { headers: H })).json();
} while (s.status === "queued" || s.status === "processing");
if (s.status !== "done") throw new Error(s.error ?? s.status);
// 3. Télécharger le MP3
const audio = await fetch(s.audio_url, { headers: H });
fs.writeFileSync("narration.mp3", Buffer.from(await audio.arrayBuffer()));Paramètres facultatifs
speed (de 0,5 à 2, 1 par défaut), pause_ms (accepté, mais avec Voizum 2 il ne change rien : pour une pause, écrivez <#1.5#> dans le texte), language ("auto" ou es, en, de, fr, pt, it, ru, nl, pl, zh, ja, ko, hi, ar, tr, id, ro ; par défaut, elle est détectée à partir du texte) et loudness_normalization (true pour que toutes les voix sortent au même niveau). Les valeurs d'état sont queued, processing, done, error et canceled. La référence complète est sur https://voizum.com/docs, avec une spécification OpenAPI sur https://voizum.com/openapi.json et une version en texte brut pour les assistants de code IA sur https://voizum.com/llms.txt.
Textes longs, lots et dialogues
Une requête accepte jusqu'à 600 000 caractères, soit environ 10 heures de parole, et revient en un seul MP3. Inutile de découper un long script en morceaux et de les recoller vous-même : la tâche le fait en interne et la consultation de l'état montre la progression (parts_done, parts_total, percent).
Pour beaucoup de pièces courtes, utilisez POST /tts/batch : 100 éléments au maximum, 1 200 000 caractères au total (environ 20 heures). Chaque élément a son propre job_id et son propre fichier, mais le minimum de 100 crédits n'est facturé qu'une fois pour tout le lot, et non à chaque requête. Huit courts messages d'application coûtent 800 crédits envoyés un par un, et 100 en lot.
Pour une conversation dans un seul fichier (une intro de podcast, une publicité à deux voix), utilisez POST /tts/dialogue avec un tableau turns ordonné, jusqu'à 5 voix différentes. Elle est facturée comme un audio normal, selon les caractères de tout le script.
Utiliser votre voix clonée par l'API
Le clonage se fait une seule fois sur le site et coûte 199 crédits ; ensuite, la voix n'est qu'un voice_id de plus et chaque génération est facturée comme avec n'importe quelle autre voix. Il n'y a pas de point d'accès de clonage dans l'API, volontairement : l'enregistrement est l'étape où l'on veut écouter avant de s'engager. Enregistrez de 15 à 60 secondes de votre seule voix, coupées sur une pause et non au milieu d'un mot, et parlez comme vous voulez que la narration sonne, car l'intonation est copiée elle aussi.
Vos voix clonées peuvent parler les 17 langues : un seul enregistrement en français narre donc aussi la version anglaise, espagnole ou allemande de votre chaîne. Ne clonez que votre propre voix ou une voix que vous avez le droit d'utiliser.
La brancher sur n8n, Make ou Zapier
Aucune plateforme d'automatisation n'a besoin d'un module Voizum spécifique : toutes trois ont une étape HTTP générique, et l'API se résume à trois appels simples. Le seul choix de conception est la façon d'attendre l'audio : interroger en boucle, ou laisser l'API vous rappeler avec webhook_url.
L'option webhook (POST /tts uniquement) envoie un POST avec event, id, status (completed ou error), voice_id, duration_seconds et credits à la fin de la tâche, avec jusqu'à trois nouvelles tentatives. Ce doit être une URL https publique : un n8n auto-hébergé sur localhost ne peut pas la recevoir, interrogez alors en boucle.
n8n
Un nœud HTTP Request avec des identifiants Header Auth (Authorization, valeur Bearer sk_voizum_…), puis une boucle pour l'attente :
- HTTP Request : POST https://voizum.com/api/v1/tts avec un corps JSON contenant text et voice_id.
- Nœud Wait de quelques secondes, puis HTTP Request : GET /tts/{{ $json.job_id }}.
- Nœud If : si status vaut done, on continue ; si queued ou processing, retour à Wait ; si error, on arrête l'exécution.
- HTTP Request sur audio_url avec les mêmes identifiants et le format de réponse réglé sur Fichier ; le binaire part ensuite vers Drive, S3 ou votre étape de montage vidéo.
Make et Zapier
Dans Make, le module « Make a request » de l'application HTTP envoie le POST avec l'en-tête Authorization. Dans Zapier, Webhooks by Zapier fait la même chose avec une action POST ou Custom Request. Dans les deux cas, la façon la plus propre d'attendre est un second scénario ou Zap qui démarre à partir d'un webhook personnalisé (Make) ou d'un déclencheur Catch Hook (Zapier) : passez cette URL en webhook_url, et quand il se déclenche, interrogez GET /tts/{id} et téléchargez audio_url avec votre clé.
Erreurs et bonnes pratiques en production
Chaque erreur a la même forme, { error: { code, message } }. Programmez en vous appuyant sur code, qui est stable, jamais sur message, qui est un texte pour humains et peut changer.
- Envoyez un Idempotency-Key à chaque POST /tts (l'identifiant de votre vidéo ou de votre ligne convient). Si une erreur réseau vous force à réessayer, vous récupérez la même tâche avec un 200 et vous n'êtes pas facturé deux fois.
- Enregistrez le job_id dès que vous le recevez. Si votre processus plante, GET /tts liste vos tâches récentes avec un curseur, et vous pouvez filtrer avec ?status=done.
- Interrogez toutes les quelques secondes, ou attendez eta_seconds, plutôt qu'en boucle serrée.
- Téléchargez et gardez votre propre copie : le MP3 est conservé 4 jours, puis le fichier est supprimé.
- Une erreur ? DELETE /tts/{id} annule une tâche encore en file et la rembourse intégralement. Une fois en cours de traitement, elle ne peut plus être annulée. Si une tâche se termine en erreur, ses crédits sont rendus automatiquement.
- N'appelez jamais l'API depuis le navigateur ou une application mobile : la clé serait visible de tous. Appelez-la depuis votre serveur, et faites parler votre interface à votre serveur.
- Changez la clé si elle a pu fuiter. En générer une nouvelle révoque l'ancienne immédiatement : mettez donc à jour la variable d'environnement juste après.
| code | HTTP | Que faire |
|---|---|---|
| no_autorizado | 401 | Clé absente, incorrecte ou révoquée |
| saldo_insuficiente | 402 | Pas assez de crédits achetés ; la réponse indique combien il vous en faut |
| voz_no_encontrada | 404 | Ce voice_id n'est pas dans votre bibliothèque : ajoutez-le d'abord |
| texto_demasiado_largo | 400 | Plus de 600 000 caractères : découpez le texte |
| limite_peticiones | 429 | Attendez le nombre de secondes de Retry-After, puis réessayez |
| demasiados_en_cola | 429 | Trop de tâches en cours : laissez-en finir quelques-unes |
| servicio_no_disponible | 503 | Réessayez plus tard avec un délai croissant (backoff) |
Combien coûte une API de synthèse vocale ?
L'API consomme les mêmes crédits que le site : 60 crédits pour 1 000 caractères (environ 60 par minute d'audio), avec un minimum de 100 par requête. Une voix off YouTube de 10 minutes représente environ 9 850 caractères, soit 591 crédits. Elle ne fonctionne qu'avec des crédits achetés, qui n'expirent jamais et s'obtiennent sans abonnement ; les crédits gratuits mensuels obtenus avec Google ne valent que pour le générateur du site.
Ci-dessous, le coût par minute d'audio avec le forfait le moins cher de chaque service, tel que publié en septembre 2026. Voizum est affiché avec le pack Máxi, celui qui a le meilleur prix par crédit. Les montants sont en euros pour toutes les marques afin de pouvoir les comparer.
| Service | Par minute d'audio (forfait d'entrée) | API incluse dans ce forfait | Crédits non utilisés |
|---|---|---|---|
| Voizum | 0,013 € | Oui | N'expirent jamais |
| MiniMax | 0,043 € | Non, facturée à part | Expirent au bout de 2 mois |
| ElevenLabs | 0,171 € | Oui | Perdus à la résiliation |
| Narakeet | 0,173 € | Oui | N'expirent jamais |
| TTSMaker | 0,040 € | Non, facturée à part | Perdus chaque mois |
Vous ne voulez pas écrire de code ?
Si vous voulez générer de l'audio pendant que vous discutez avec Claude ou ChatGPT, vous n'avez pas besoin de l'API : le connecteur Voizum ajoute à l'assistant des outils pour générer et lister les voix, se connecte avec votre compte et suit les mêmes règles que le site, crédits gratuits mensuels compris. La configuration prend quelques minutes depuis la page Connecter.
Et si vous avez seulement besoin d'une page qui lit du texte dans le navigateur du visiteur, la Web Speech API intégrée aux navigateurs suffit. Elle est gratuite, mais sonne robotique, change d'un appareil à l'autre et ne vous donne aucun fichier. Une API TTS vaut le coup dès que vous voulez une voix naturelle dans un MP3 que vous pouvez publier.
Sources consultées
- Documentation n8n : nœud HTTP Request (en anglais)
- Documentation n8n : identifiants HTTP Request (Header Auth, en anglais)
- Documentation développeur Make : envoyer des requêtes (en anglais)
- Aide Zapier : envoyer des webhooks dans les Zaps (en anglais)
- Brouillon IETF : l'en-tête HTTP Idempotency-Key (en anglais)
- MDN : en-tête Retry-After (en anglais)
- MDN : Web Speech API
- OWASP : guide de gestion des secrets (en anglais)
Nos guides vous sont utiles ? Ajoutez Voizum comme source préférée et Google vous montrera davantage de nos contenus.
Ajouter sur Google ↗
2Comment choisir une API de synthèse vocale ?
Partez de ce que vous construisez, pas de la démo de la voix. Ce qui divise le marché, c'est la latence face à la longueur : un assistant vocal a besoin de la première syllabe en quelques centaines de millisecondes et diffuse l'audio au fur et à mesure, alors qu'un narrateur veut qu'un script de 40 minutes sorte en un seul fichier propre. Peu d'API sont bonnes dans les deux cas, et les moins chères au caractère sont souvent les moins naturelles.