Guide d'intégration de l'API Text-to-Speech

Par Équipe éditoriale AudioLecture · Mis à jour 2026-11-18

Cette documentation explique comment intégrer notre API de synthèse vocale dans vos workflows éditoriaux. Vous apprendrez à authentifier vos requêtes, à générer des fichiers audio à partir de texte et à gérer les limites techniques. Les exemples concrets couvrent les usages standards et les cas spécifiques aux lecteurs malvoyants ou dyslexiques.

Nous détaillons les paramètres obligatoires, le choix des voix et la gestion des langues. Vous trouverez des extraits de code prêts à l’emploi pour Python et Node.js, ainsi que des explications sur les formats audio supportés. L’objectif est de vous permettre d’automatiser la production d’audio avec une précision technique immédiate.

Guide d'intégration de l'API Text-to-Speech

Questions fréquentes

Quelle est la structure JSON exacte de la requête ?

La requête POST vers /v1/audio/speech contient les champs : model (tts-1 ou tts-1-hd), input (texte, max 4096 caractères), voice (l'un des 8 presets), response_format (mp3, wav, opus, flac, pcm), speed (0,25–4,0) et language (code ISO optionnel). L'authentification s'effectue via l'en-tête Authorization: Bearer.

Comment changer la voix après la première requête ?

Vous modifiez simplement le champ voice dans le corps JSON de votre prochaine requête POST. Les huit voix (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion) sont disponibles immédiatement. Aucune configuration supplémentaire ni réinitialisation de la clé n'est nécessaire pour changer de preset vocal.

La clé API fonctionne-t-elle avec les SDK tiers ?

Oui, la clé fonctionne avec les SDK OpenAI officiels. Il suffit de modifier l'attribut base_url vers https://api.getbn880.com/v1. L'API suit la même forme de requête que l'endpoint de synthèse vocale d'OpenAI, garantissant une compatibilité immédiate pour les intégrations existantes.

Quelle est la différence entre tts-1 et tts-1-hd ?

Il n'y a aucune différence technique ou tarifaire entre les modèles tts-1 et tts-1-hd. Ils utilisent le même moteur de synthèse et offrent le même prix de 10 $ par million de caractères. Vous pouvez choisir l'un ou l'autre selon vos préférences de nommage sans impact sur le coût.

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

Vous devez diviser manuellement votre texte en plusieurs parties de 4096 caractères maximum. Envoyez chaque partie via une requête POST distincte, puis assemblez les fichiers audio retournés pour obtenir le fichier final. L'API ne gère pas automatiquement le fractionnement ou le jointure des fichiers.

Les paramètres de vitesse sont-ils persistants ?

Non, les paramètres ne sont pas persistants entre les requêtes. Vous devez inclure le champ speed (de 0,25 à 4,0) dans le corps JSON de chaque requête POST. Si vous omettez ce champ, la vitesse par défaut sera appliquée pour cette génération spécifique uniquement.

Comment récupérer le fichier audio généré ?

Le fichier audio est retourné directement dans le corps de la réponse HTTP de la requête POST. Il n'est pas stocké sur nos serveurs après la réponse. Vous devez traiter le flux binaire reçu et l'enregistrer localement ou sur votre infrastructure selon le format demandé (mp3, wav, etc.).

L'API supporte-t-elle les requêtes parallèles ?

Les requêtes sont traitées séquentiellement, une après l'autre. En cas de charge, une requête peut attendre dans une file d'attente. Cela peut augmenter le temps de génération pour les textes longs, bien que la vitesse typique soit proche du temps réel pour les contenus étendus.

Que signifie le code d'erreur 429 ?

Le code 429 signale un dépassement de quota. Par défaut, la limite est de 60 requêtes par minute par clé API. Cependant, avant votre premier rechargement, cette limite est réduite à 10 requêtes par minute. Pour restaurer la capacité standard de 60 requêtes, il suffit d’effectuer un rechargement sur votre compte.

Dois-je spécifier la langue pour chaque requête ?

Cela dépend du script. Si le texte est en latin et non en anglais, la langue est devinée comme anglais par défaut. Pour les textes latins non anglais, vous devez spécifier le paramètre language avec le code ISO approprié pour garantir une synthèse correcte des 23 langues supportées.

Les formats OPUS sont-ils lisibles par tous les players ?

Le format OPUS est l'un des formats supportés avec MP3, WAV, FLAC et PCM. Bien que largement utilisé, sa compatibilité dépend du lecteur audio. Pour une compatibilité maximale universelle, le format MP3 ou WAV est souvent privilégié, mais OPUS est disponible pour l'optimisation de la bande passante.

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). Si vous créez un compte avec email et mot de passe, aucun crédit d'essai n'est attribué. Vous pouvez effectuer un rechargement via USDT (TRC-20) pour activer le service.

La clé peut-elle être utilisée sur plusieurs serveurs ?

Oui, une clé API unique peut être utilisée sur plusieurs serveurs ou environnements. Une seule clé est active par compte. Si vous en émettez une nouvelle, l'ancienne devient inactive immédiatement. La limite de 60 requêtes par minute s'applique à la clé, quel que soit le serveur d'appel.

Y a-t-il une limite de durée pour un fichier audio ?

Il n’y a pas de limite de durée, mais 4096 caractères par requête. La génération est environ en temps réel (25 caractères/seconde). Pour les textes longs, divisez le texte en plusieurs requêtes et assemblez les fichiers audio résultants pour obtenir le contenu audio complet.

Première requête

curl

curl https://api.getbn880.com/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.getbn880.com/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.getbn880.com/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

Prérequis et création de clé API

Illustration d'onde sonore pour: Prérequis et création de clé API

Pour commencer, créez un compte sur getbn880.com. La connexion via Google offre un crédit d'essai de 0,50 $ (50 000 caractères, valide 7 jours). L'inscription par email et mot de passe ne fournit pas de crédit initial. Votre clé API s'affiche sur la page /get-api-key/, accompagnée de votre solde et d'un exemple cURL prêt à l'emploi.

Inscription et génération de la clé Bearer

L'inscription se fait sur la page dédiée. Une fois connecté, votre clé Bearer unique est visible. Elle permet d'authentifier toutes vos requêtes API vers le point d'entrée JSON.

  • Crédit d'essai de 0,50 $ avec connexion Google
  • Aucun crédit initial avec email/mot de passe
  • Clé unique visible immédiatement après connexion

Révoquer et régénérer une clé active

Une seule clé est active par compte. Si vous la perdez ou souhaitez la sécuriser, vous pouvez en émettre une nouvelle à tout moment. L'ancienne clé devient immédiatement inactive dès la régénération.

Sécurité de l'authentification

Ajoutez l'en-tête Authorization: Bearer tts-... à vos requêtes HTTP. La clé doit rester confidentielle. Aucun autre mécanisme d'authentification (OAuth, tokens JWT) n'est utilisé en dehors de ce simple jeton Bearer.

Première requête avec cURL

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

Pour tester l'intégration d'AudioLecture, envoyez une requête POST JSON à l'endpoint https://api.getbn880.com/v1/audio/speech. Cette méthode standard permet de générer un fichier audio directement depuis la ligne de commande, idéal pour valider la configuration avant le développement. L'exemple ci-dessous illustre la structure minimale requise. Le serveur traite la demande et renvoie le fichier audio binaire dans le corps de la réponse, sans passage par une URL temporaire.

La commande cURL suivante génère un fichier MP3 avec la voix 'milo'. Assurez-vous de remplacer VOTRE_CLE par votre clé Bearer unique.

sub1

curl -X POST "https://api.getbn880.com/v1/audio/speech" \ -H "Authorization: Bearer VOTRE_CLE" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Bonjour, ceci est un test pour les lecteurs dyslexiques.", "voice": "milo", "response_format": "mp3"}'

sub2

Trois champs sont strictement obligatoires pour toute requête de synthèse : - model : utilisez tts-1 ou tts-1-hd pour le même moteur. - input : le texte à convertir, limité à 4096 caractères par requête. - voice : sélectionnez parmi les 8 presets (ex. milo pour un ton conversationnel). Le paramètre response_format est également requis pour définir le codec audio (mp3, wav, opus, flac, pcm).

sub3

La réponse HTTP contient le fichier audio binaire correspondant à vos paramètres. Les métadonnées de la requête (temps, statut) sont conservées pour la facturation, mais le fichier généré n'est pas stocké sur nos serveurs. En cas d'erreur (par exemple, clé invalide ou limite de caractères dépassée), un code d'erreur HTTP standard est retourné avec un message explicatif.

Première requête avec cURL

Utilisation avec le SDK OpenAI

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

Pour intégrer AudioLecture avec votre application Python ou Node.js, vous pouvez utiliser le SDK OpenAI officiel. Il suffit de redéfinir l'URL de base (base_url) pour pointer vers notre point d'entrée API, ce qui permet de réutiliser la logique d'appel standard sans écrire de clients HTTP personnalisés.

Cette approche garantit une compatibilité immédiate avec vos outils existants. Vous conservez les méthodes familiarisées tout en dirigeant les requêtes vers notre infrastructure de synthèse vocale dédiée aux éditeurs.

Configuration de la variable base_url

Le SDK OpenAI utilise une variable d'environnement ou un paramètre de configuration pour déterminer l'endpoint. Pour AudioLecture, cette variable doit être ajustée pour pointer vers notre infrastructure spécifique.

Pointeur vers https://api.getbn880.com/v1

L'URL exacte à configurer est https://api.getbn880.com/v1. Cette adresse remplace le point d'entrée par défaut d'OpenAI dans vos scripts de génération audio.

Utilisation des classes Speech et Client

Une fois la configuration effectuée, utilisez les classes Client et Speech du SDK. Vous pouvez ainsi invoquer la synthèse vocale avec votre clé API Bearer, en transmettant le texte et la voix souhaitée comme d'habitude.

Paramètres de requête détaillés

Illustration d'onde sonore pour: Paramètres de requête détaillés

L'API propose deux modèles, tts-1 et tts-1-hd, partageant le même moteur et le même tarif. Ce dernier offre une qualité supérieure sans surcoût, permettant d'ajuster le compromis entre débit et fidélité selon les besoins éditoriaux. Chaque requête génère un fichier audio synthétique marqué par un filigrane inaudible.

Le choix de la voix et du format reste central pour l'accessibilité. Les huit voix préenregistrées couvrent les besoins narratifs et informatifs. Le format de réponse s'adapte aux contraintes de lecture, qu'il s'agisse de compression standard ou de qualité sans perte pour les archives éditoriales.

Modèles : tts-1 et tts-1-hd

Les modèles tts-1 et tts-1-hd utilisent exactement le même moteur de synthèse. Ils partagent le même tarif de $10 par million de caractères. Cette uniformité simplifie l'intégration technique pour les éditeurs qui peuvent basculer entre les deux sans modifier leur logique de facturation.

  • Moteur de synthèse identique pour les deux modèles
  • Tarification unifiée à 0,01 $ par 1 000 caractères
  • Pas de différence de latence ni de format

Voix disponibles et leurs caractéristiques

Huit voix sont disponibles, basées sur des enregistrements licenciés sous licence CC BY 4.0, extraits des lectures de livres audio du domaine public de LibriVox via le jeu de données LibriTTS-R. Ces voix incluent des timbres féminins (Aria, Nova, Luna, Sage) et masculins (Felix, Milo, Atlas, Orion), chacun adapté à des contextes spécifiques comme la narration ou l'information.

Le choix de la voix influence la lisibilité pour les publics dyslexiques ou malvoyants. Par exemple, Atlas offre un ton neutre idéal pour l'information brute, tandis que Luna convient mieux à la narration littéraire. Toutes les voix peuvent prononcer les 23 langues supportées.

  • Aria : narratrice chaleureuse et claire
  • Nova : ton lumineux et dynamique
  • Luna : voix douce pour le storytelling
  • Sage : calme et instructional
  • Felix : énergique, idéal pour les promos
  • Milo : conversationnel et amical
  • Atlas : neutre, adapté à l'information
  • Orion : voix profonde pour la documentation

Format de réponse et vitesse (0.25–4.0)

L'API accepte cinq formats de sortie : MP3, WAV, OPUS, FLAC et PCM. Le MP3 est recommandé pour une compression standard et une compatibilité universelle. Le WAV et le FLAC offrent une qualité sans perte, utiles pour les archives. L'OPUS et le PCM servent à des besoins de flux spécifiques ou de traitement audio direct.

Le paramètre speed permet d'ajuster la vitesse de lecture entre 0.25 et 4.0. Pour les lecteurs dyslexiques, une vitesse légèrement réduite peut améliorer la compréhension. La génération suit un rythme proche du temps réel, soit environ 25 caractères par seconde pour les textes longs.

  • Formats : MP3, WAV, OPUS, FLAC, PCM
  • Vitesse ajustable de 0.25 à 4.0
  • Qualité sans perte avec WAV/FLAC

Gestion des langues et paramètres

Illustration d'onde sonore pour: Gestion des langues et paramètres

L'API détermine la langue de synthèse à partir du script du texte fourni si le paramètre language n'est pas spécifié. Pour les textes en alphabet latin, la langue par défaut est l'anglais. Il est recommandé de définir explicitement le code ISO pour les textes en latin mais non anglais, afin d'éviter toute ambiguïté dans la prononciation.

Cette gestion automatique assure une compatibilité immédiate avec les contenus éditoriaux variés. Les voix générées s'adaptent aux 23 langues supportées, garantissant une restitution précise pour les lecteurs dyslexiques ou malvoyants, quel que soit l'origine linguistique du texte source.

Code ISO optionnel ou détection automatique

Le champ language est optionnel. L'API analyse les caractères pour inférer la langue. Cette détection fonctionne sur la base du script (latin, cyrillique, arabe, etc.).

Pour les langues non-latines ou les mélanges complexes, fournir le code ISO (ex: fr, de, ja) garantit la voix appropriée sans déduction automatique.

  • Détection automatique basée sur le script du texte.
  • Paramètre language en code ISO pour forcer la voix cible.
  • Précision accrue pour les textes multilingues ou ambigus.

Détection par défaut en anglais pour le latin

Tout texte en alphabet latin sans paramètre language explicite est traité comme de l'anglais. Cela inclut le français, l'espagnol ou l'allemand.

Pour obtenir une prononciation correcte dans ces langues, il faut impérativement ajouter le code langue correspondant dans la requête JSON.

  • Défaut : Anglais pour tout texte latin non spécifié.
  • Exemple : Texte français sans language sera prononcé avec un accent anglais.
  • Ajoutez "language": "fr" pour une voix française précise.

Liste des 23 langues supportées

L'API supporte 23 langues spécifiques. Chaque voix peut parler n'importe laquelle de ces langues avec une qualité constante.

Les langues non listées (comme le vietnamien ou le thaï) ne sont pas supportées, même si le texte utilise un script reconnu.

  • Arabe, Chinois, Danois, Néerlandais, Anglais, Finnois, Français, Allemand, Grec, Hébreu, Hindi, Italien, Japonais, Coréen, Malais, Norvégien, Polonais, Portugais, Russe, Espagnol, Swahili, Suédois, Turc.
Gestion des langues et paramètres

Limites et erreurs courantes

Illustration d'onde sonore pour: Limites et erreurs courantes

La limitation à 4 096 caractères par requête nécessite de découper les textes longs. La génération suit un traitement séquentiel, ce qui peut entraîner une attente en file d'attente lors des pics de charge.

Le débit est plafonné à 60 requêtes par minute par clé active. Avant le premier rechargement, cette limite est réduite à 10 requêtes par minute. Elle s'applique indépendamment du volume de données traité.

Limite de 4096 caractères par requête

Chaque appel API ne peut contenir plus de 4 096 caractères. Pour les contenus éditoriaux longs, il faut segmenter le texte et assembler les fichiers audio générés.

La vitesse de synthèse est d'environ 25 caractères par seconde pour les textes longs. Les phrases courtes prennent quelques secondes.

  • Maximum de 4 096 caractères (espaces et ponctuation inclus) par payload JSON.
  • Découpage manuel requis pour les articles ou chapitres de livres.

Taux de 60 requêtes par minute

La limite standard est de 60 requêtes par minute par clé. Pour les nouveaux comptes sans rechargement, le plafond est de 10 requêtes par minute.

Cette contrainte s'applique dès la première utilisation. Elle est indépendante du volume de données traité.

  • 60 req/min après le premier top-up.
  • 10 req/min avant le premier top-up.

Codes d'erreur HTTP standards

Une erreur 429 indique que la limite de débit est atteinte. Il faut ralentir la production ou répartir la charge.

Les requêtes échouées sont remboursées intégralement. Vérifiez les en-têtes pour gérer les files d'attente.

Les erreurs 4xx signalent une clé invalide ou des paramètres manquants. Les erreurs 5xx sont temporaires.

  • 429 Too Many Requests : dépassement du quota par minute.
  • 401 Unauthorized : clé Bearer manquante ou invalide.
  • 400 Bad Request : paramètre input dépassant 4 096 caractères.

Formats audio supportés

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

Le format MP3 offre une compression standard adaptée à la diffusion web courante. Les formats WAV et FLAC garantissent une qualité audio sans perte, idéale pour les archives éditoriales ou les besoins de précision acoustique des lecteurs malvoyants.

MP3 pour une compression standard

Le MP3 est le format par défaut recommandé pour la plupart des intégrations API. Il assure un bon équilibre entre la taille du fichier et la fidélité sonore, permettant une transmission rapide des contenus audio générés.

WAV et FLAC pour une qualité sans perte

Le format WAV conserve l'intégralité des données audio brutes, tandis que le FLAC offre une compression sans perte plus efficace. Ces formats sont privilégiés pour les publications professionnelles où la fidélité du signal est critique.

OPUS et PCM pour des flux spécifiques

Le format OPUS est pris en charge pour une compression efficace. Le format PCM fournit le signal audio brut non compressé. Le choix dépend des besoins de traitement en aval et des contraintes de bande passante.

Formats audio supportés

Exemples de code complets

Illustration d'onde sonore pour: Exemples de code complets

Ces exemples illustrent l'intégration technique pour les éditeurs. Le script Python utilise le SDK OpenAI pour générer rapidement des fichiers audio à partir de contenus textuels, tandis que la requête Node.js native offre une alternative légère sans dépendances externes.

La gestion des limites de taux (60 requêtes/min) est cruciale pour les gros volumes. Une logique de réessai avec temporisation évite les interruptions lors de la conversion de longs textes en audio pour les lecteurs malvoyants.

Script Python avec OpenAI SDK

Configurez base_url sur https://api.getbn880.com/v1 et utilisez la clé Bearer. Ce script génère un fichier MP3 à partir d'un texte court.

La réponse contient directement le flux audio binaire, prêt à être sauvegardé ou diffusé immédiatement dans vos applications d'accessibilité.

  • Utilisation de la classe OpenAI standard
  • Compatibilité avec les clés tts-...
  • Gestion automatique des formats audio

Requête Node.js native

Une requête fetch simple en Node.js permet d'envoyer le texte et de recevoir le fichier audio sans installer le SDK complet.

Cette approche est idéale pour les environnements serverless ou les micro-services éditoriaux où la légèreté du code prime sur la commodité des abstractions.

Gestion des erreurs de rate limit

En cas de dépassement des 60 requêtes par minute, l'API renvoie une erreur 429. Il faut implémenter une logique de réessai avec temporisation exponentielle.

Cette gestion assure la continuité du service pour les gros volumes de texte, même si les requêtes sont traitées séquentiellement sous charge.

Écoutez les 8 voix

Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. Pour les éditeurs, l'accessibilité est essentielle pour inclure les lecteurs dyslexiques.

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. LibriVox public-domain audiobooks
  4. openai-node on GitHub
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. MDN: Web Speech API
  7. Creative Commons Attribution 4.0
  8. OpenAI API reference: create speech
  9. Python documentation
  10. Node.js documentation
  11. openai-python on GitHub
  12. W3C WAI: making audio and video accessible

Plus sur ce site