Documentation de l'API de synthèse vocale

Par L'équipe éditoriale Hagy · Mis à jour 2026-11-19

Cette documentation explique comment intégrer notre API de synthèse vocale dans vos applications pour créer des voix off naturelles, idéales pour les contes et histoires pour enfants. Vous découvrirez les bases techniques nécessaires pour envoyer du texte et recevoir des fichiers audio, en utilisant simplement cURL ou les SDK OpenAI existants.

Nous détaillons chaque paramètre, des voix disponibles aux formats audio, ainsi que les limites de quota et la gestion des erreurs. Que vous soyez débutant ou expérimenté, vous trouverez ici les exemples concrets et les codes prêts à l’emploi pour démarrer rapidement avec ConteVoix sur hagy.info.

Documentation de l'API de synthèse vocale

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.mp3

Python (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
ariafemme
novafemme
lunafemme
sagefemme
felixhomme
milohomme
atlashomme
orionhomme
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Obtenir une clé API

Illustration d'onde sonore pour: 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

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é

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

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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
Gestion de la vitesse et langue

Limites et quotas

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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.

Avatar de la voix aria
ariafemme
Avatar de la voix nova
novafemme
Avatar de la voix luna
lunafemme
Avatar de la voix sage
sagefemme
Avatar de la voix felix
felixhomme
Avatar de la voix milo
milohomme
Avatar de la voix atlas
atlashomme
Avatar de la voix orion
orionhomme

23 langues

Chaque voix peut parler n'importe laquelle de ces langues.

Sources et lectures complémentaires

  1. Wikipedia
  2. W3C WAI: making audio and video accessible
  3. Node.js documentation
  4. Tether (USDT)
  5. Python documentation
  6. OpenAI API reference: create speech
  7. openai-node on GitHub
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. LibriTTS-R corpus (OpenSLR 141)
  10. curl documentation
  11. LibriVox public-domain audiobooks
  12. TRON developer hub: TRC-20

Plus sur ce site