Questions fréquentes
Quelle est la structure de la requête ?
Utilisez POST sur /v1/audio/speech avec un corps JSON contenant model, input, voice, response_format et speed. La clé API s'envoie via l'en-tête Authorization: Bearer tts-... . Le champ language est optionnel pour préciser la langue.
Comment changer l'URL de base ?
Configurez votre SDK ou client HTTP pour utiliser https://api.hagy.info/v1 comme URL de base. Cela permet de réutiliser les endpoints standards comme /v1/audio/speech sans modifier la structure des requêtes ou des paramètres envoyés.
Les SDK OpenAI fonctionnent-ils nativement ?
Oui, en changeant simplement l'URL de base vers https://api.hagy.info/v1. Vous pouvez utiliser les mêmes bibliothèques et méthodes d'appel que pour l'API OpenAI, ce qui facilite l'intégration dans vos projets existants sans code complexe.
Quels formats audio sont disponibles ?
Vous pouvez choisir entre mp3, wav, opus, flac et pcm via le paramètre response_format. Ces formats couvrent la plupart des besoins de lecture web ou de traitement audio, offrant un choix flexible pour la qualité et la taille des fichiers.
Comment gérer les textes longs ?
Divisez manuellement votre texte en segments de 4096 caractères ou moins. Envoyez chaque segment via une requête distincte, puis assemblez les fichiers audio générés pour obtenir la narration complète. Cette méthode garantit le respect des limites techniques de l'API.
Quelle est la limite de caractères ?
Chaque requête accepte jusqu'à 4096 caractères dans le champ input. Si votre texte dépasse cette limite, vous devez le fractionner en plusieurs appels. Les espaces et la ponctuation sont comptabilisés comme des caractères dans cette limite.
Combien de requêtes par minute ?
La limite est de 60 requêtes par minute par clé API. Avant le premier rechargement, vous êtes limité à 10 requêtes par minute. Ces quotas s'appliquent à l'ensemble des appels effectués avec votre clé active.
Comment réinitialiser sa clé API ?
Vous pouvez émettre une nouvelle clé à tout moment depuis votre tableau de bord. La clé précédente devient immédiatement inactive dès que la nouvelle est générée. Cela permet de sécuriser votre accès en cas de perte ou de compromission.
Les voix supportent-elles l'italique ?
Non, l'API ne supporte pas le SSML ni les balises de mise en forme comme l'italique. Le ton est déterminé par le choix de la voix (ex : sage pour l'instructionnel) et non par des tags dans le texte.
Peut-on mixer plusieurs voix ?
L'API génère un fichier audio par requête avec une seule voix. Pour mixer, vous devez générer chaque partie séparément avec la voix souhaitée, puis assembler les fichiers audio via un outil externe ou votre propre code de traitement.
L'API est-elle compatible avec les webhooks ?
Non, l'API ne supporte pas les webhooks. Vous devez effectuer des requêtes synchrones pour recevoir le fichier audio directement dans la réponse. Les requêtes sont traitées dans l'ordre d'arrivée.
Comment tester l'API gratuitement ?
Inscrivez-vous via Google pour obtenir 0,50 $ de crédit (environ 50 000 caractères) valable 7 jours. Vous pouvez également utiliser une inscription par e-mail, mais elle ne donne pas droit à ce crédit d'essai initial.
Que signifie le statut 'queued' ?
Cela indique que votre requête est en attente dans une file d'attente avant traitement. Les requêtes sont traitées séquentiellement ; sous charge, le temps d'attente peut augmenter. Le statut change une fois la synthèse audio commencée ou terminée.
Les fichiers audio ont-ils un filigrane ?
Oui, chaque fichier généré contient un filigrane inaudible indiquant qu'il s'agit de parole synthétique. Ce marquage est intégré automatiquement lors de la création du fichier audio et ne nécessite aucune action supplémentaire de votre part.
Première requête
curl
curl https://api.hagy.info/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.hagy.info/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.hagy.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | femme |
nova | femme |
luna | femme |
sage | femme |
felix | homme |
milo | homme |
atlas | homme |
orion | homme |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Obtenir une clé API
Pour utiliser l'API de synthèse vocale, commencez par créer un compte sur la page /get-api-key/. Vous pouvez vous inscrire via Google ou avec une adresse e-mail et un mot de passe. Chaque compte est lié à un site spécifique.
Une fois inscrit, votre clé API unique est affichée immédiatement. Elle sert à authentifier toutes vos requêtes via l'en-tête Authorization. Vous pouvez la réinitialiser à tout moment si nécessaire.
Création de compte
Accédez à /get-api-key/ pour vous inscrire. L'authentification par Google offre un crédit d'essai de 0,50 $ valide 7 jours. Les comptes créés avec e-mail et mot de passe débutent sans crédit.
Le compte est individuel et indépendant selon le site visité. Aucune vérification bancaire n'est requise pour obtenir votre clé initiale.
- Authentification Google ou e-mail/mot de passe
- Crédit d'essai de 0,50 $ (7 jours) pour l'inscription Google
- Compte lié à la plateforme spécifique
Génération de la clé
Votre clé API est visible dès la connexion sur le tableau de bord. Elle commence par le préfixe tts- et sert à authentifier vos appels via l'en-tête Authorization: Bearer.
Une seule clé active est associée à votre compte à un instant donné. Elle est visible immédiatement après la création du compte.
- Format : tts-...
- Authentification par en-tête Bearer
- Clé unique et active par compte
Réinitialisation de la clé
Vous pouvez générer une nouvelle clé à tout moment depuis les paramètres du compte. Dès la génération, l'ancienne clé devient immédiatement inactive.
Ce processus est utile en cas de perte ou de doute sur la sécurité. La nouvelle clé remplace l'ancienne sans interruption de service pour vos futures requêtes.
- Révocation instantanée de l'ancienne clé
- Activation immédiate de la nouvelle clé
- Disponible depuis le tableau de bord
Première requête avec cURL
Envoyez une requête POST à https://api.hagy.info/v1/audio/speech avec votre clé Bearer. Le corps JSON définit le modèle, le texte, la voix et le format audio souhaité.
Commande POST
Utilisez cURL pour envoyer les données. Remplacez YOUR_API_KEY par votre clé et Votre texte ici par le contenu à synthétiser.
- curl -X POST https://api.hagy.info/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Votre texte ici", "voice": "luna", "response_format": "mp3"}'
Corps JSON
Le corps contient model ("tts-1" ou "tts-1-hd"), input (texte jusqu'à 4096 caractères), voice (ex: "luna" pour les contes), et response_format.
Réponse audio
La réponse retourne le fichier audio directement dans le corps de la réponse. Pour les formats comme MP3, vous pouvez enregistrer ce flux dans un fichier local.
Utilisation du SDK OpenAI
Vous pouvez utiliser les SDK officiels OpenAI en modifiant simplement l'URL de base. Pointez base_url vers https://api.hagy.info/v1 et utilisez votre clé API ConteVoix. Cela permet de réutiliser la logique de requête standard sans écrire de code personnalisé pour l'intégration.
Cette approche simplifie grandement l'intégration pour les développeurs indépendants. Elle garantit une compatibilité immédiate avec les bibliothèques connues, réduisant le temps de développement pour vos projets de narration ou d'applications web.
Changement de base_url
Définissez la variable d'environnement OPENAI_BASE_URL sur https://api.hagy.info/v1. Assurez-vous que votre clé API commence par tts- et est passée via l'en-tête Authorization: Bearer.
Exemple de code Python
Utilisez le package openai. Configurez le client avec la nouvelle URL de base. Envoyez une requête POST vers /v1/audio/speech avec le texte et la voix souhaités.
- Installation :
pip install openai - Initialisation :
OpenAI(base_url="https://api.hagy.info/v1", api_key="tts-...") - Appel :
client.audio.speech.create(...)
Exemple de code Node.js
Installez le package openai. Configurez l'instance avec la même URL de base et votre clé. Appelez la méthode audio.speech.create pour recevoir le fichier audio.
- Installation :
npm install openai - Configuration :
new OpenAI({ baseURL: 'https://api.hagy.info/v1', apiKey: 'tts-...' }) - Exécution :
await openai.audio.speech.create({ model: 'tts-1', voice: 'luna', input: '...' })
Paramètres de la requête
Chaque requête POST doit préciser le modèle et la voix synthétique. Le corps JSON contient le texte à convertir, limité à 4096 caractères par appel.
Modèle : tts-1 ou tts-1-hd
Choisissez entre tts-1 et tts-1-hd. Ils utilisent le même moteur de synthèse et le même tarif. La différence réside uniquement dans la qualité audio générée.
Voix : choix parmi 8 presets
Sélectionnez une voix parmi huit presets. Pour un conte pour enfants, luna offre une tonalité douce et narrative, idéale pour la lecture de contes. aria propose une narration claire et chaleureuse.
- aria : narratrice chaleureuse
- nova : voix dynamique
- luna : douce et narrative
- sage : voix instructional calme
- felix : voix énergique
- milo : conversationnel
- atlas : neutre et informatif
- orion : voix profonde
Format : mp3, wav, opus, flac, pcm
Spécifiez le format de sortie via response_format. Le choix dépend de votre intégration : le MP3 est universel, le WAV pour une qualité sans perte, et l'Opus pour une compression légère.
Gestion de la vitesse et langue
La vitesse de synthèse s'ajuste via le paramètre speed, accepté entre 0.25 et 4.0. Une valeur de 1.0 correspond au débit naturel. Réduire la vitesse ralentit la lecture, idéal pour les contes destinés aux enfants, tandis qu'une vitesse élevée convient aux annonces dynamiques.
Paramètre speed (0.25–4.0)
Ajustez ce paramètre pour adapter le rythme à votre contenu narratif. Chaque modification affecte la durée de génération, mais le prix reste calculé par caractère texte envoyé.
Détection automatique de la langue
L'API devine la langue depuis le script du texte. Le texte latin non spécifié est traité comme de l'anglais par défaut. Pour des langues comme le français ou l'espagnol en script latin, la détection peut échouer si le contexte est ambigu.
Force de la langue ISO
Pour garantir une prononciation correcte, définissez explicitement le paramètre language avec un code ISO. Cela évite les erreurs de synthèse sur des textes multilingues ou des noms propres. Les 23 langues supportées incluent le français, l'arabe ou le japonais.
- Code ISO recommandé pour le français :
fr - Code ISO recommandé pour l'anglais :
en

Limites et quotas
Votre clé API est soumise à une limite de 60 requêtes par minute. Cette contrainte s'applique globalement à chaque clé active, indépendamment du nombre de serveurs ou d'instances qui l'utilisent simultanément. Une limite réduite de 10 requêtes par minute s'applique aux nouveaux comptes jusqu'à leur premier rechargement.
Chaque appel API ne peut traiter qu'un texte de 4096 caractères maximum. Pour les contes plus longs, vous devez découper votre texte en segments respectant cette limite et assembler les fichiers audio générés.
En cas de charge, les requêtes sont traitées séquentiellement. Une requête peut donc attendre dans une file d'attente si le service est sollicité, ce qui peut allonger le temps de réponse par rapport à la durée de synthèse seule.
60 requêtes par minute
Votre clé API est soumise à une limite de 60 requêtes par minute. Cette contrainte s'applique globalement à chaque clé active, indépendamment du nombre de serveurs ou d'instances qui l'utilisent simultanément. Une limite réduite de 10 requêtes par minute s'applique aux nouveaux comptes jusqu'à leur premier rechargement.
- Limite standard : 60 requêtes/min par clé.
- Limite initiale : 10 requêtes/min avant premier paiement.
Limite de 4096 caractères
Chaque appel API ne peut traiter qu'un texte de 4096 caractères maximum. Pour les contes plus longs, vous devez découper votre texte en segments respectant cette limite et assembler les fichiers audio générés.
- Taille max : 4096 caractères par requête.
- Espaces et ponctuation inclus dans le compte.
File d'attente sous charge
En cas de charge, les requêtes sont traitées séquentiellement. Une requête peut donc attendre dans une file d'attente si le service est sollicité, ce qui peut allonger le temps de réponse par rapport à la durée de synthèse seule.
- Traitement séquentiel sous charge.
Gestion des erreurs
Lorsque le service rencontre un problème, il renvoie des codes HTTP précis pour identifier la cause. Les erreurs 4xx indiquent généralement une requête mal formée ou une clé invalide, tandis que les 5xx signalent une indisponibilité temporaire du serveur.
Erreurs 4xx et 5xx
Vérifiez d'abord vos paramètres : modèle, voix et format doivent être conformes à la documentation. Si l'erreur persiste, contactez-nous par e-mail.
Requêtes échouées gratuites
Si la synthèse échoue après l'envoi du texte, le montant est intégralement remboursé sur votre solde. Aucun crédit n'est déduit pour ces tentatives invalides.
Gestion des timeouts
Pour les textes longs, le traitement peut prendre du temps. Implémentez une logique de réessai avec temporisation exponentielle pour gérer les délais sans interrompre votre application.
Exemples complets
Ces exemples illustrent les cas d'usage concrets de l'API ConteVoix, du court au long format.
Ils couvrent la génération simple, le traitement par lots et l'application narrative spécifique.
Texte court en français
Une phrase simple suffit pour tester la voix Aria en format MP3. La réponse retourne un fichier audio binaire prêt à être intégré dans une application.
Exemple : `curl -X POST https://api.hagy.info/v1/audio/speech -H 'Authorization: Bearer tts-...' -H 'Content-Type: application/json' -d '{"model": "tts-1", "input": "Bonjour et bienvenue.", "voice": "aria", "response_format": "mp3"}' -o audio.mp3`
Texte long avec découpage
Pour un texte dépassant 4096 caractères, divisez-le en segments. Générez chaque segment indépendamment puis assemblez les fichiers audio résultants pour reconstituer le flux complet.
Ce processus respecte la limite par requête tout en maintenant la cohérence de la narration sur la durée.
- Découpez le texte en blocs de 4096 caractères max.
- Exécutez une requête POST par bloc.
- Joignez les fichiers audio en sortie.
Voix Luna pour un conte
La voix Luna, douce et narrative, est idéale pour les contes pour enfants. Appliquez-la à un texte court en français pour une ambiance apaisante.
Utilisez le format WAV pour une qualité sans perte ou MP3 pour une taille réduite. La vitesse par défaut convient à la narration.
- Voix : luna
- Langue : fr (définie explicitement)
- Format : wav ou mp3
- Modèle : tts-1
Écoutez les 8 voix
Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. Sa voix claire et vive transforme chaque phrase en une expérience engageante, parfaite pour les jeunes publics ou les contenus dynamiques.
23 langues
Chaque voix peut parler n'importe laquelle de ces langues.
Sources et lectures complémentaires
- Wikipedia
- W3C WAI: making audio and video accessible
- Node.js documentation
- Tether (USDT)
- Python documentation
- OpenAI API reference: create speech
- openai-node on GitHub
- LibriTTS-R paper (arXiv 2305.18802)
- LibriTTS-R corpus (OpenSLR 141)
- curl documentation
- LibriVox public-domain audiobooks
- TRON developer hub: TRC-20
