Documentation API TTS : Intégration pour les systèmes d'annonces

Par Équipe éditoriale VoixTransit · Mis à jour 2026-11-19

Ce guide explique comment intégrer notre API TTS dans vos systèmes d'annonces publiques. Vous apprendrez à authentifier vos requêtes, à envoyer des textes et à recevoir des fichiers audio via cURL ou le SDK OpenAI.

Conçu pour les équipes de transport, ce document couvre les points essentiels : modèles, voix, formats et limites. Il vous permet de générer des annonces claires et fiables à grande échelle sans complexité inutile.

Documentation API TTS : Intégration pour les systèmes d'annonces

Questions fréquentes

Quelle est la structure de la requête POST ?

Envoyez un JSON au endpoint POST https://api.456a.info/v1/audio/speech. Le corps doit inclure le champ model (tts-1 ou tts-1-hd), input (texte jusqu'à 4096 caractères), voice (l'une des 8 presets), response_format (mp3, wav, opus, flac, pcm) et speed (0.25–4.0). L'en-tête Authorization: Bearer tts-... est obligatoire pour authentifier la requête.

Comment changer l'URL de base pour le SDK OpenAI ?

Modifiez la variable base_url de votre client SDK OpenAI pour pointer vers https://api.456a.info/v1. Utilisez ensuite la méthode standard pour générer la parole. Cela permet de réutiliser les SDK officiels OpenAI avec notre API en remplaçant simplement l'URL de base et en fournissant votre clé API VoixTransit.

Quels sont les formats audio disponibles ?

Vous pouvez choisir parmi mp3, wav, opus, flac et pcm via le champ response_format. Ces formats s'adaptent à différents besoins de stockage et de lecture. Le format mp3 est recommandé pour une compatibilité universelle, tandis que le wav ou le flac offrent une qualité sans perte pour les systèmes de diffusion audio professionnels.

Quelle voix choisir pour des annonces neutres ?

Pour des annonces neutres, privilégiez la voix Atlas. Elle est décrite comme neutre et adaptée aux nouvelles. Elle convient parfaitement aux annonces publiques standardisées où l'émotion doit rester minimale. Les voix Sage ou Milo peuvent aussi convenir selon le ton souhaité, mais Atlas reste le choix le plus objectif pour les messages informatifs.

Comment spécifier une langue autre que l'anglais ?

Définissez le champ language avec le code ISO approprié dans votre requête JSON. Si ce champ est omis, la langue est déduite du script (le texte latin par défaut en anglais). Pour les textes latins en français, allemand ou espagnol, spécifiez explicitement language pour éviter une détection incorrecte et garantir la prononciation correcte.

Que faire si le texte dépasse 4096 caractères ?

Découpez votre texte en plusieurs parties de 4096 caractères maximum. Envoyez chaque partie via une requête distincte à l'API. Une fois les fichiers audio générés, vous devrez les assembler manuellement ou via un script pour obtenir le fichier audio complet. L'API ne gère pas nativement le découpage ou l'assemblage des longs textes.

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, cette limite est de 10 requêtes par minute. Si vous dépassez cette limite, vos requêtes peuvent être ralenties ou rejetées. Pour les équipes de transport à fort volume, assurez-vous de gérer le rate limiting côté client.

Les requêtes échouées sont-elles comptabilisées ?

Non, les requêtes échouées sont gratuites. Si la synthèse échoue, le montant est entièrement remboursé sur votre solde. Seules les requêtes abouties avec succès sont facturées au tarif de 0,01 $ par 1 000 caractères. Cela vous protège des coûts lors des tests ou des pics de charge temporaires.

Puis-je modifier la vitesse de parole ?

Oui, vous pouvez ajuster la vitesse via le champ speed, qui accepte des valeurs entre 0.25 et 4.0. La valeur par défaut est généralement 1.0. Cette fonctionnalité permet d'adapter le débit de parole aux annonces rapides ou aux explications détaillées. Une vitesse plus élevée réduit le temps de génération, tandis qu'une vitesse plus lente améliore la clarté.

Le modèle tts-1-hd offre-t-il une meilleure qualité ?

Oui, les modèles tts-1 et tts-1-hd utilisent exactement le même moteur de synthèse et offrent une qualité sonore identique. La seule différence réside dans le nom du modèle dans votre requête API. Le prix est également le même pour les deux options, vous permettant de choisir celui qui s’intègre le plus simplement à votre code existant sans compromis sur la clarté des annonces.

Comment révoquer une clé API compromise ?

Générez une nouvelle clé API depuis votre tableau de bord sur la page /get-api-key/. La nouvelle clé devient active immédiatement, tandis que l'ancienne est désactivée à l'instant même. Vous n'avez pas besoin de notifier vos clients ou de mettre à jour les configurations de manière complexe, car l'ancienne clé ne fonctionnera plus.

Les fichiers audio contiennent-ils un filigrane audible ?

Oui, chaque fichier audio généré contient un filigrane inaudible qui marque la parole comme synthétique. Ce filigrane est invisible à l'oreille humaine et ne modifie pas la qualité de l'audio. Il permet d'identifier que le contenu est de la parole synthétique.

Quelle est la durée moyenne de génération ?

La génération prend environ une seconde par seconde de parole pour les textes longs, soit 25 caractères par seconde. Pour les phrases courtes, cela prend quelques secondes. Les requêtes sont traitées séquentiellement, donc une file d'attente peut survenir en cas de charge élevée. La latence dépend du nombre de requêtes simultanées.

Dois-je installer une dépendance spécifique pour l'API ?

Non, vous pouvez utiliser n'importe quel client HTTP ou le SDK OpenAI. Aucune dépendance propriétaire n'est requise. Le SDK OpenAI fonctionne directement en modifiant l'URL de base. Vous pouvez également utiliser des outils comme cURL ou des bibliothèques HTTP standard dans votre langage de programmation préféré pour interagir avec l'endpoint /v1/audio/speech.

Première requête

curl

curl https://api.456a.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.456a.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.456a.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, créez un compte sur /get-api-key/. L'authentification Google offre un crédit d'essai de 0,50 $ (environ 50 000 caractères) valable 7 jours, tandis que les comptes par e-mail n'en reçoivent pas. Une fois inscrit, vous accédez à votre tableau de bord dédié aux équipes de transport.

Création de compte sur /get-api-key/

Création de compte sur /get-api-key/

Accédez à la page d'inscription pour initialiser votre accès. Le processus est rapide et permet de générer immédiatement les identifiants nécessaires à l'intégration de votre système d'annonces.

Génération d'une clé Bearer unique

Génération d'une clé Bearer unique

Chaque compte dispose d'une seule clé API active (format tts-...). Cette clé sert d'identifiant unique pour authentifier vos requêtes POST vers l'endpoint /v1/audio/speech. Elle est visible directement sur votre tableau de bord.

  • Format : Bearer tts-...

Révocation instantanée lors du renouvellement

Si vous révoquez ou régénérez votre clé via le tableau de bord, l'ancienne devient inactive immédiatement. Aucun délai de propagation n'est requis, ce qui garantit une sécurité immédiate pour vos systèmes en production.

Première requête avec cURL

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

Pour générer une annonce, envoyez une requête POST à l'endpoint /v1/audio/speech. L'authentification se fait via un en-tête Authorization: Bearer contenant votre clé unique. Ce format standardise l'intégration avec vos systèmes d'annonces existants.

Envoi POST vers /v1/audio/speech

Utilisez cURL pour envoyer vos données. Assurez-vous que votre clé API est valide et active. L'endpoint accepte les requêtes JSON pour une intégration rapide dans vos scripts de diffusion.

Corps JSON avec modèle, input et voix

Le corps de la requête doit inclure le model (tts-1 ou tts-1-hd), le input (texte jusqu'à 4096 caractères) et la voice (ex: aria, atlas). Vous pouvez aussi définir le speed et le language.

  • model: tts-1 ou tts-1-hd
  • input: texte brut ou annonce
  • voice: nom de la voix (ex: atlas)
  • response_format: mp3, wav, etc.

Réception du fichier audio binaire

En cas de succès, vous recevez un fichier audio binaire. Si la synthèse échoue, aucun frais n'est appliqué. Stockez ce fichier pour votre diffusion ou testez-le immédiatement avec un lecteur compatible.

Utilisation avec le SDK OpenAI

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

Pour utiliser notre API avec le SDK OpenAI, il suffit de modifier l'URL de base (base_url) pour pointer vers https://api.456a.info/v1 tout en conservant votre clé API VoixTransit dans l'en-tête Authorization.

La structure de la requête reste identique à celle d'OpenAI, ce qui permet une intégration rapide dans vos scripts Python ou JavaScript existants sans réécrire la logique de génération audio.

Changement de base_url vers notre API

Pointez votre client SDK vers https://api.456a.info/v1. Utilisez une clé commençant par tts- pour l'authentification Bearer. Les SDK officiels OpenAI fonctionnent directement avec cette configuration.

  • Base URL: https://api.456a.info/v1
  • Auth: Authorization: Bearer tts-...

Même structure de requête que OpenAI

Le corps de la requête utilise les champs model, input, voice et response_format. Cette conformité garantit que vos fichiers de configuration habituels restent valides sans modifications majeures.

Compatibilité avec les clients Python et JS

Les bibliothèques openai en Python et JavaScript interprètent correctement nos endpoints. Adaptez simplement la variable d'environnement OPENAI_BASE_URL ou passez base_url dans le constructeur du client.

Modèles et voix disponibles

Illustration d'onde sonore pour: Modèles et voix disponibles

L'API propose deux modèles, tts-1 et tts-1-hd, qui utilisent le même moteur de synthèse et le même tarif. Le choix dépend uniquement de vos besoins en qualité audio sans impact sur le coût par million de caractères.

Modèles : tts-1 et tts-1-hd (mêmes prix)

Vous pouvez utiliser indifféremment tts-1 ou tts-1-hd dans vos requêtes. Les deux offrent la même précision et le même prix, simplifiant la gestion de vos appels API sans surcoût pour une haute qualité.

Voix : Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion

Huit voix sont disponibles pour vos annonces de transport. Elles couvrent des timbres variés : narratrice claire (Aria), dynamique (Nova), douce (Luna) ou institutionnelle (Atlas). Toutes supportent les 23 langues listées.

  • Aria (femme, narratrice)
  • Nova (femme, dynamique)
  • Luna (femme, douce)
  • Sage (femme, instruction)
  • Felix (homme, promo)
  • Milo (homme, conversation)
  • Atlas (homme, neutre)
  • Orion (homme, documentaire)

Sélection de la voix par son nom dans le corps JSON

Indiquez simplement le nom de la voix dans le champ voice de votre corps JSON. Le système génère l'audio avec le timbre correspondant immédiatement.

Formats audio supportés

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

Le format audio choisi détermine l'équilibre entre la taille du fichier et la compatibilité avec vos systèmes d'annonce. L'API permet de spécifier le format souhaité directement via le paramètre response_format dans la requête JSON.

Chaque format offre des avantages techniques distincts selon que vous priorisez l'efficacité du stockage ou la fidélité du signal audio pour vos haut-parteurs publics.

MP3 : compression standard, usage général

Le MP3 est le format par défaut recommandé pour la plupart des cas d'usage. Sa compression réduite permet une transmission rapide des fichiers audio via l'API, idéale pour les intégrations web.

Ce format assure une compatibilité universelle avec la grande majorité des lecteurs audio et des contrôleurs d'annonce sans nécessiter de conversions supplémentaires.

  • Taille de fichier réduite pour un transfert efficace.
  • Compatibilité native avec la plupart des lecteurs audio modernes.

WAV : qualité sans perte, pour les systèmes embarqués

Le format WAV offre une qualité audio brute, sans compression, garantissant une fidélité sonore parfaite pour les haut-parteurs publics.

Il est particulièrement adapté aux systèmes embarqués ou aux lecteurs qui nécessitent un signal audio direct sans décodage complexe, assurant une lecture instantanée et précise des annonces d'alerte.

  • Qualité audio originale sans dégradation.
  • Idéal pour les lecteurs audio simples et les systèmes embarqués.

OPUS, FLAC, PCM : formats alternatifs disponibles

Pour des besoins spécifiques, l'API supporte également les formats OPUS, FLAC et PCM. Ces formats permettent de s'adapter à des infrastructures techniques particulières ou à des exigences de stockage spécifiques.

Le choix dépend de la capacité de traitement de vos lecteurs finaux et de vos contraintes de bande passante ou de stockage local.

  • OPUS : compression efficace.
  • FLAC : compression sans perte pour l'archivage.
  • PCM : données audio brutes non compressées.
Formats audio supportés

Paramètres de vitesse et langue

Illustration d'onde sonore pour: Paramètres de vitesse et langue

Le paramètre speed permet d'ajuster la vitesse de lecture entre 0,25 et 4,0 fois la vitesse normale, offrant une flexibilité précise pour les annonces publiques. La langue peut être forcée via un code ISO ou détectée automatiquement pour le texte latin, garantissant une prononciation exacte sans configuration complexe pour les équipes de transport.

Cette approche simplifie l'intégration des messages d'alerte et des annonces programmées, tout en évitant les erreurs de détection linguistique courantes dans les environnements multilingues des réseaux de transport.

Vitesse : de 0.25 à 4.0 fois la vitesse normale

Ajustez la rapidité de synthèse pour adapter le message au contexte : annonces calmes ou alertes pressantes.

La vitesse influence directement la durée de génération ; des valeurs élevées peuvent accélérer le traitement sous charge.

  • Valeur minimale : 0.25 (très lent)

Langue : code ISO optionnel pour forcer la détection

Utilisez le champ language avec un code ISO pour imposer une langue spécifique, indépendamment du texte saisi.

Cette méthode évite les ambiguïtés lors de l'envoi de textes dans des langues peu courantes ou mixtes.

  • Supporte les 23 langues listées dans le catalogue

Détection automatique par défaut pour le texte latin

Sans spécification, le système déduit la langue depuis la scripte ; le texte latin bascule par défaut sur l'anglais.

Pour d'autres langues en alphabet latin, définissez explicitement le paramètre language pour garantir la prononciation correcte.

  • Détection par scripte pour les textes latins

Limites et erreurs courantes

Illustration d'onde sonore pour: Limites et erreurs courantes

L'API impose des contraintes techniques précises qui nécessitent une adaptation de votre workflow de génération. Le respect de ces limites garantit une intégration stable pour vos systèmes d'annonces et d'alertes.

Comprendre ces seuils vous permet d'anticiper les besoins en architecture et d'éviter les interruptions de service lors des pics de diffusion.

Limite de 4096 caractères par requête

Chaque appel API ne peut contenir plus de 4096 caractères, espaces et ponctuation incluss. Pour les annonces longues ou les messages d'alerte détaillés, vous devez découper votre texte en segments respectant cette limite.

Les fichiers audio générés pour chaque segment doivent ensuite être assemblés côté client ou par votre système pour restituer le message complet sans coupure audible.

  • Les caractères spéciaux et l'espacement comptent dans le total.
  • Une seule requête échoue si le texte dépasse le seuil.

Limite de 60 requêtes par minute par clé

Chaque clé API est limitée à 60 requêtes par minute (10 par minute avant le premier rechargement). Cette contrainte s'applique par clé active et non par adresse IP.

Pour les équipes de transport générant des annonces simultanées sur plusieurs terminaux, une seule clé peut saturer rapidement. Utilisez le endpoint GET /v1/voices pour vérifier les voix, langues, formats et prix disponibles.

  • La limite est par clé API, pas par utilisateur final.
  • Le dépassement déclenche une erreur 429.

Gestion des erreurs HTTP 429 et 500

Une erreur 429 indique que vous avez dépassé le quota de 60 requêtes par minute. Le serveur vous invite à attendre et à réessayer avec une logique de backoff exponentiel.

Une erreur 500 signale un problème interne lors de la synthèse. La demande n'est pas débitée, vous pouvez la réessayer immédiatement sans perte de crédit.

  • Les erreurs de taux (429) sont temporaires.
  • Les erreurs serveur (500) sont remboursées intégralement.

Traitement des textes longs

Illustration d'onde sonore pour: Traitement des textes longs

Pour les annonces de grande envergure, découpez votre texte en segments de 4096 caractères maximum. Chaque segment génère un fichier audio distinct que votre système doit assembler séquentiellement.

Découpage en segments de 4096 caractères

Divisez le texte source respectant cette limite stricte. Envoyez chaque partie via un POST séparé à l'endpoint /v1/audio/speech.

Assemblage des fichiers audio générés

Recevez les binaires audio un par un. Concaténez-les dans l'ordre pour reconstituer le message complet diffusé aux usagers.

Gestion de la file d'attente sous charge

Les requêtes sont traitées séquentiellement. En cas de charge élevée, la génération peut attendre dans une file d'attente, rallongeant légèrement le temps de réponse total.

Écoutez les 8 voix

Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. Votre texte brut n'est utilisé qu'une seule fois pour générer le fichier audio correspondant et n'est jamais conservé pour l'entraînement de nos modèles.

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. FFmpeg documentation
  3. OpenAI API reference: create speech
  4. openai-node on GitHub
  5. TRON developer hub: TRC-20
  6. Node.js documentation
  7. openai-python on GitHub
  8. MDN: Web Speech API
  9. Tether (USDT)
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. curl documentation
  12. ISO 639 language codes

Plus sur ce site