Une API de synthèse vocale en Python : enregistrer, diffuser, réessayer
Une API de synthèse vocale dans le cloud est le moyen le plus court de donner une voix à un script Python : pas de modèle à télécharger, pas de carte graphique, une requête HTTP. Ce guide montre l’API vocale de SuperClonica depuis Python avec la bibliothèque requests, du premier fichier à la diffusion en flux de longs textes et à la gestion des limites comme il se doit pour un script en production.
Il vous faut une clé : connectez-vous à SuperClonica avec Google ou GitHub et créez-la dans la section API de votre espace de travail. L’offre gratuite donne une minute d’audio par jour.
Enregistrer un mp3
Gardez la clé dans une variable d’environnement et envoyez le texte avec une voix et une langue :
import os, requests; KEY = os.environ["SUPERCLONICA_KEY"]; r = requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": "Bonjour depuis Python !", "voice": "F1", "language": "fr", "format": "mp3"}, timeout=120); r.raise_for_status(); open("hello.mp3", "wb").write(r.content)
Sans "format", la réponse arrive en Ogg Vorbis, le fichier le plus léger ; wav est aussi disponible. Une requête accepte jusqu’à 20 000 caractères.
Diffuser un long texte
Avec "stream": true, le serveur envoie l’audio pendant qu’il est encore produit : vous pouvez l’écrire sur disque ou le passer à un lecteur dès le premier morceau :
with requests.post("https://superclonica.com/api/v1/speech", headers={"Authorization": "Bearer " + KEY}, json={"text": long_text, "voice": "M2", "language": "fr", "stream": True}, stream=True, timeout=120) as r: r.raise_for_status(); f = open("speech.ogg", "wb"); [f.write(chunk) for chunk in r.iter_content(8192)]; f.close()
Dans nos mesures, le premier son est arrivé dès 300 ms quelle que soit la longueur du texte, et environ 16 000 caractères ont été lus en 25,6 secondes.
Voix et limites
Listez les voix que votre clé peut utiliser ; chaque élément a un id, un nom, un type (stock, own, bought ou catalog) et une langue :
voices = requests.get("https://superclonica.com/api/v1/voices", headers={"Authorization": "Bearer " + KEY}, timeout=30).json()["items"]
Vérifiez ce qui reste de votre offre avant une grosse tâche :
usage = requests.get("https://superclonica.com/api/v1/usage", headers={"Authorization": "Bearer " + KEY}, timeout=30).json(); print(usage["plan"], usage["available_seconds"])
Erreurs et nouvelles tentatives
Envoyez un en-tête Idempotency-Key avec chaque requête, par exemple une empreinte du texte : une requête répétée après un délai dépassé attend alors la même tâche au lieu de lire et compter le texte deux fois.
- 429 : la fenêtre de 10 minutes de l’offre est épuisée ; attendez les secondes de Retry-After et renvoyez.
- 503 : la file est pleine ; attendez Retry-After secondes et renvoyez avec la même clé.
- 413 : le texte est plus long que ce que votre offre permet dans une fenêtre ; découpez-le.
- 401 : la clé manque, est fausse ou a été supprimée.
- Un texte échoué ne compte pas dans l’offre.