Guide d'intégration de l'API de synthèse vocale

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

Cette page vous guide pas à pas pour intégrer notre API de synthèse vocale dans vos projets d’apprentissage des langues ou vos outils pédagogiques. Vous y trouverez des exemples concrets, du choix des paramètres à la gestion des erreurs, pour générer rapidement des fichiers audio clairs et naturels à partir de n’importe quel texte.

Que vous utilisiez cURL, le SDK OpenAI ou un script Python, cette documentation technique couvre tous les aspects de l’intégration : création de compte, gestion des clés, limites de taux et formats supportés. Vous apprendrez aussi comment traiter les longs textes et adapter la voix à votre public cible, sans fioritures ni complexité inutile.

Guide d'intégration de l'API de synthèse vocale

Questions fréquentes

Comment obtenir une clé API pour ce service ?

Inscrivez-vous sur /get-api-key/ via Google ou email/mot de passe. Vous recevrez une clé unique au format Bearer. Une nouvelle clé peut être émise à tout moment, ce qui invalie immédiatement l’ancienne. Chaque compte dispose d’une seule clé active pour authentifier vos requêtes auprès de l’API.

Quelle est la structure JSON requise ?

Envoyez un POST à /v1/audio/speech avec un corps JSON contenant : model (tts-1 ou tts-1-hd), input (texte), voice (préréglage), response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0) et language (code ISO optionnel). L’authentification se fait via l’en-tête Authorization: Bearer votre_clé.

Peut-on utiliser le SDK OpenAI officiel ?

Oui, le SDK OpenAI fonctionne en modifiant l’URL de base vers https://api.bgd3.info/v1 et en utilisant votre clé API. Cela permet d’utiliser les mêmes méthodes d’envoi de texte et de gestion des réponses audio sans modifier le code client, grâce à la compatibilité du format de requête.

Quels sont les modèles disponibles ?

Deux modèles sont disponibles : tts-1 et tts-1-hd. Ils utilisent le même moteur de synthèse et ont le même prix. Le choix dépend uniquement de la qualité audio souhaitée, sans différence de coût ni de fonctionnalités entre les deux options proposées par l’API.

Quelle est la limite de caractères par requête ?

Chaque requête peut contenir jusqu’à 4096 caractères. Au-delà, vous devez diviser votre texte en plusieurs parties. Cette limite s’applique au texte brut envoyé dans le champ input, incluant les espaces et la ponctuation, pour garantir un traitement optimal par le moteur de synthèse.

Comment gérer les textes de plus de 4096 caractères ?

Divisez votre texte en segments de 4096 caractères maximum. Envoyez chaque segment via une requête distincte, puis joignez les fichiers audio résultants. Cette méthode manuelle ou scriptée permet de traiter des documents longs sans perdre la continuité du contenu audio généré par l’API.

Quels formats audio puis-je demander ?

Vous pouvez choisir parmi mp3, wav, opus, flac et pcm via le champ response_format. Ces formats couvrent les besoins courants en compression et qualité. Le format par défaut n’est pas spécifié, mais tout format valide sera retourné directement dans la réponse de l’API.

Comment changer la vitesse de lecture ?

Utilisez le champ speed avec une valeur entre 0.25 et 4.0. Une valeur de 1.0 correspond à la vitesse normale. Ajustez ce paramètre pour adapter la lecture à vos besoins pédagogiques ou de contenu, en veillant à rester dans les limites acceptées par le moteur.

Quelle est la limite de requêtes par minute ?

La limite est de 60 requêtes par minute par clé API. Avant le premier rechargement, elle est de 10 requêtes par minute. Ces limites sont strictes et appliquées par clé. Dépassez-les pour recevoir un code 429 ou attendre que le quota se réinitialise.

Que signifie le code d'erreur 429 ?

Le code 429 indique que vous avez dépassé la limite de 60 requêtes par minute (ou 10 avant le premier rechargement). Attendez que le quota se réinitialise ou réduisez la fréquence de vos appels. Ce code garantit que vous ne serez pas facturé pour les requêtes limitées.

L'API retourne-t-elle un flux continu ?

Non, l’API ne propose pas de streaming ni de WebSocket. Elle retourne le fichier audio complet une fois la synthèse terminée. Les requêtes sont traitées séquentiellement, ce qui peut entraîner des délais si le serveur est chargé, mais assure une livraison fiable du fichier final.

Comment spécifier la langue du texte ?

Utilisez le champ language avec un code ISO (ex: fr, en, de). Si non spécifié, la langue est déduite du script (le texte latin est par défaut en anglais). Pour les textes latins non anglais, définissez explicitement le champ language pour éviter les erreurs de prononciation.

La clé API expire-t-elle ?

Non, la clé API ne expire pas. Elle reste valide tant que votre compte existe. Vous pouvez en générer une nouvelle à tout moment via le tableau de bord, ce qui invalide immédiatement l’ancienne. Le solde et les paramètres restent associés à votre compte.

Y a-t-il une documentation pour les développeurs ?

Oui, cette page sert de documentation technique. Elle décrit les endpoints, les champs JSON et les limites. Vous pouvez également consulter /get-api-key/ pour un exemple curl prêt à l’emploi. Aucune documentation externe ou SDK propriétaire n’est fourni, l’API est conçue pour être simple et directe.

Comment tester l'API sans payer ?

Inscrivez-vous via Google pour recevoir 0,50 $ de crédit d’essai, valable 7 jours (environ 50 000 caractères). Les comptes créés par email n’ont pas ce crédit. Utilisez ces fonds pour tester les voix et formats sans engagement. Les requêtes échouées sont remboursées intégralement.

Les requêtes sont-elles traitées en parallèle ?

Non, les requêtes sont traitées séquentiellement. Sous charge, une requête peut attendre dans une file d’attente. Cela explique pourquoi la génération prend environ une seconde par 25 caractères. Cette approche garantit l’ordre de traitement mais peut ralentir le débit lors de pics d’utilisation simultanée.

Première requête

curl

curl https://api.bgd3.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.bgd3.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.bgd3.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 votre clé API

Illustration d'onde sonore pour: Obtenir votre clé API

Pour commencer à utiliser l'API de synthèse vocale de VoixApprenants, vous devez d'abord créer un compte sur bgd3.info. L'inscription se fait soit via Google, soit avec une adresse e-mail et un mot de passe. Cette étape simple vous donne accès à votre tableau de bord personnel.

Création de compte via Google ou email

Création de compte via Google ou email

Choisissez la méthode d'authentification qui vous convient le mieux. Les comptes créés avec Google reçoivent un crédit d'essai de 0,50 $ (environ 50 000 caractères) valide 7 jours. Les comptes créés par e-mail et mot de passe démarrent sans ce crédit d'essai.

Localisation de la clé API

Localisation de la clé API

Une fois connecté, votre clé API unique est affichée sur la page de gestion. Vous verrez également votre solde actuel, le crédit d'essai restant et le nombre de caractères consommés. C'est ici que vous retrouverez l'identifiant nécessaire pour authentifier vos requêtes.

  • Utilisez la clé affichée dans le champ 'API Key'.
  • La clé commence par 'tts-'.
  • Un seul jeton actif est valide à la fois.

Gestion des clés actives et révoquées

Vous pouvez révoquer votre clé actuelle et en générer une nouvelle à tout moment depuis le tableau de bord. Dès la nouvelle clé est émise, l'ancienne devient immédiatement invalide. Cette fonction est utile si vous partagez votre clé ou souhaitez changer d'environnement de développement.

Première requête avec cURL

Illustration d'onde sonore pour: Première requête avec cURL

Envoyez une requête POST à l'endpoint /v1/audio/speech avec votre clé Bearer. Le corps contient le texte, le modèle et la voix souhaités. C'est la méthode la plus directe pour tester l'API sans dépendance externe.

La réponse retourne le fichier audio binaire directement. Assurez-vous de traiter le flux de sortie comme un fichier binaire et non comme du texte pour éviter les corruptions.

Structure du corps de la requête JSON

Le JSON doit inclure model (tts-1 ou tts-1-hd), input (texte, max 4096 caractères), voice (ex: nova, atlas) et response_format (mp3, wav, etc.).

Ajoutez speed (0.25–4.0) si nécessaire. Le champ language est optionnel mais recommandé pour les textes en latin non anglais.

  • model: "tts-1" ou "tts-1-hd"
  • input: chaîne de caractères
  • voice: preset parmi les 8 disponibles
  • response_format: mp3, wav, opus, flac, pcm

Exemple complet pour générer un fichier audio

Voici une commande cURL standard pour générer un audio MP3 avec la voix 'nova' :

curl -X POST https://api.bgd3.info/v1/audio/speech \ -H "Authorization: Bearer tts-..." \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Bonjour à tous, ceci est un test.", "voice": "nova", "response_format": "mp3"}' \ -o output.mp3

Vérification de la réponse audio

Le serveur retourne le fichier audio directement dans le corps de la réponse HTTP. Aucun objet JSON avec un URL n'est généré ici.

Vérifiez que le fichier output.mp3 est lisible avec un lecteur standard. En cas d'erreur (ex: texte trop long), un code 4xx sera retourné avec un message explicite.

Utilisation avec le SDK OpenAI

Illustration d'onde sonore pour: Utilisation avec le SDK OpenAI

L'API fonctionne avec la même structure de corps de requête que l'endpoint de synthèse vocale d'OpenAI. Cela permet d'utiliser directement les SDK officiels en modifiant simplement l'URL de base pour pointer vers notre infrastructure.

Changement de l'URL de base (base_url)

Pointez votre client vers https://api.bgd3.info/v1 au lieu de l'URL par défaut. Cette modification suffit pour rediriger toutes les requêtes vers notre endpoint POST /v1/audio/speech sans changer la logique de votre code.

Configuration de la clé d'authentification

Incluez votre clé API dans l'en-tête Authorization: Bearer tts-.... Cette clé est unique par compte et garantit que votre consommation est correctement facturée sur votre solde VoixApprenants.

Compatibilité avec les clients officiels

Les clients officiels OpenAI fonctionnent nativement avec nos paramètres. Vous n'avez pas besoin de développer un client personnalisé ou d'ajouter des dépendances spécifiques pour interagir avec notre service de synthèse vocale.

Paramètres de la requête

Illustration d'onde sonore pour: Paramètres de la requête

La requête API exige la définition précise du modèle et de la voix pour garantir un rendu audio adapté à votre contenu pédagogique. Le choix technique détermine la qualité et le style de la narration sans complexité supplémentaire.

Ces paramètres s'ajustent facilement pour varier le ton, que ce soit pour une leçon calme ou une annonce dynamique. Voici comment configurer chaque élément essentiel dans votre payload JSON.

Sélection du modèle (tts-1 ou tts-1-hd)

Vous pouvez choisir entre tts-1 et tts-1-hd. Ces deux modèles utilisent le même moteur de synthèse et le même tarif, offrant ainsi une flexibilité immédiate pour vos tests ou productions sans surcoût.

Le modèle par défaut suffit pour la plupart des usages éducatifs, garantissant une clarté vocale optimale pour la compréhension des apprenants.

  • tts-1 : Modèle standard, coût unitaire unique.
  • tts-1-hd : Haute définition, même prix et moteur identique.

Choix de la voix parmi les 8 presets

Huit voix distinctes sont disponibles, allant de aria (narratrice claire) à atlas (neutre, idéal pour les nouvelles). Chaque voix peut parler n'importe lequel des 23 langues supportées, ce qui simplifie la gestion multilingue pour les enseignants.

Si la langue n'est pas spécifiée, le système devine le texte latin en anglais. Pour d'autres langues en alphabet latin, définissez toujours le paramètre language.

  • Femmes : aria, nova, luna, sage.
  • Hommes : felix, milo, atlas, orion.

Ajustement de la vitesse de lecture

Le paramètre speed accepte des valeurs entre 0.25 et 4.0. Ajuster la vitesse permet d'adapter l'écoute aux besoins spécifiques des étudiants, ralentissant pour la compréhension ou accélérant pour la révision.

Une vitesse autour de 1.0 offre un débit naturel proche du temps réel, facilitant l'immersion linguistique sans fatigue auditive excessive.

  • Plage : 0.25 à 4.0.
  • Recommandé : 1.0 pour un rythme naturel.

Formats audio supportés

Illustration d'onde sonore pour: Formats audio supportés

L'API propose quatre formats audio pour répondre à vos besoins de stockage et de lecture. Le choix dépend du compromis entre la qualité sonore, la taille du fichier et la compatibilité avec vos lecteurs ou vos outils d'apprentissage des langues.

MP3 pour une compatibilité maximale

Le format MP3 est recommandé pour la plupart des usages grâce à sa large compatibilité. Il offre un bon équilibre entre qualité sonore et taille de fichier, ce qui le rend idéal pour le partage et la diffusion en ligne.

WAV pour une qualité sans perte

Le format WAV conserve l'intégralité des données audio sans compression. Cependant, le fichier est plus volumineux que le MP3, ce qui peut ralentir le chargement sur des connexions lentes ou augmenter les coûts de stockage.

Opus et FLAC pour l'efficacité

Opus offre une compression efficace pour un streaming léger, tandis que FLAC assure une qualité sans perte avec un fichier plus volumineux que le MP3. FLAC est donc plus lourd que le MP3, contrairement à une idée reçue sur les formats sans perte.

Formats audio supportés

Limites et gestion des erreurs

Illustration d'onde sonore pour: Limites et gestion des erreurs

Pour garantir un débit stable, chaque requête POST est limitée à 4096 caractères. Si votre texte dépasse cette taille, il doit être découpé en segments plus courts puis assemblés après la réception des fichiers audio.

L’API applique une limite de 60 requêtes par minute par clé. Les comptes récents non rechargés sont limités à 10 requêtes par minute. Les tentatives excessives entraînent une erreur 429.

Limite de 4096 caractères par requête

Le champ input accepte jusqu'à 4096 caractères, espaces et ponctuation inclus. Tout texte excédant cette limite doit être scindé manuellement avant l'envoi pour éviter le rejet de la demande.

Taux de 60 requêtes par minute

Vous disposez de 60 requêtes par minute par clé API. Cette limite s'applique à l'ensemble de vos appels simultanés. Respectez le code d'erreur 429 (Too Many Requests) pour temporiser vos requêtes.

  • 60 requêtes/min pour les comptes actifs
  • 10 requêtes/min pour les nouveaux comptes sans rechargement
  • Code HTTP 429 en cas de surcharge

Gestion des erreurs courantes (4xx, 5xx)

Les erreurs 4xx indiquent généralement un problème avec votre requête (clé invalide, modèle inconnu, limite de caractères dépassée). Vérifiez vos en-têtes et le format JSON. Les erreurs 5xx sont rares et signalent un problème temporaire du serveur. En cas d'échec de synthèse, aucun frais n'est appliqué.

  • 401 : Clé API invalide ou expirée
  • 429 : Limite de taux dépassée
  • 400 : Format de requête incorrect

Traitement des longs textes

Illustration d'onde sonore pour: Traitement des longs textes

Pour les textes dépassant 4096 caractères, divisez le contenu en segments inférieurs à cette limite. Chaque segment est envoyé via une requête POST distincte, générant un fichier audio séparé. Notez que chaque appel est facturé individuellement, même s'il fait partie d'un même discours. Les espaces et la ponctuation comptent dans le total des caractères.

Découpage manuel en segments

Divisez votre texte en blocs de 4096 caractères ou moins. Envoyez chaque segment via une requête POST distincte. Notez que chaque appel est facturé séparément, même s'il fait partie d'une même unité de contenu. La génération prend environ deux secondes par segment court, mais peut être plus longue en cas de file d'attente. Limite stricte de 4096 caractères par corps de requête. Chaque segment génère un fichier audio distinct. Les espaces et ponctuation comptent dans le total.

Concaténation des fichiers audio

Récupérez les fichiers audio retournés par chaque requête. Assemblez-les séquentiellement dans l'ordre souhaité pour reconstituer le texte complet. Cette méthode garantit que chaque partie est synthétisée correctement sans perte de donnée.

Gestion de la synchronisation

La vitesse de lecture doit rester identique pour tous les segments afin d'éviter les sauts de rythme. Si vous utilisez un paramètre speed personnalisé, appliquez-le à chaque requête. Le résultat final sera une audio fluide et continue.

Exemples de code pratiques

Illustration d'onde sonore pour: Exemples de code pratiques

Ces exemples concrets illustrent l'utilisation de l'API dans les workflows courants des créateurs de contenu. Ils permettent de générer rapidement des fichiers audio clairs pour des supports pédagogiques ou des vidéos.

Le code fourni utilise le SDK OpenAI avec l'URL de base adaptée ou des requêtes HTTP natives, facilitant l'intégration dans n'importe quel projet web ou script automatisé.

Script Python avec le SDK

Utilisez le SDK OpenAI en modifiant simplement l'URL de base. Ce script génère un fichier MP3 à partir d'un texte court, en spécifiant la voix et le format souhaités.

Requête HTTP brute en JavaScript

Pour les environnements sans SDK, utilisez fetch avec un corps JSON. L'exemple montre l'envoi d'une requête POST vers l'endpoint de synthèse avec la clé d'authentification.

Gestion des paramètres de langue

Spécifiez toujours le paramètre language pour les textes en latin non anglais. Cela évite les erreurs de détection automatique et garantit une prononciation précise pour l'apprentissage des langues.

Écoutez les 8 voix

Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. Idéale pour les tutoriels techniques ou les explications théoriques, elle maintient une régularité qui favorise la concentration sur la durée.

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. IETF RFC 7845: Ogg Opus
  3. Tether (USDT)
  4. FFmpeg documentation
  5. LibriTTS-R corpus (OpenSLR 141)
  6. TRON developer hub: TRC-20
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. ISO 639 language codes
  9. MDN: Web Speech API
  10. OpenAI API reference: create speech
  11. Python documentation
  12. openai-python on GitHub

Plus sur ce site