Comment utiliser notre API TTS cloud pour générer de l'audio ?

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

Cette page explique comment intégrer notre API TTS cloud dans vos applications pour convertir du texte en fichiers audio via une simple requête HTTP. Vous découvrirez le workflow complet : de l'authentification par clé Bearer à la gestion des voix et des formats, avec des exemples concrets adaptés aux développeurs indie et aux startups.

Nous détaillons la configuration du client, le traitement des textes longs et les stratégies d'optimisation des coûts. Lisez ce guide pour comprendre les limites techniques, gérer les erreurs courantes et mettre en production une génération audio fiable, économique et sans dépendances lourges.

Comment utiliser notre API TTS cloud pour générer de l'audio ?

Questions fréquentes

Quelle SDK choisir pour l'intégration ?

Utilisez le SDK OpenAI officiel en modifiant simplement l'URL de base vers https://api.gogogold.top/v1. Le format de la requête est identique à celui de l'endpoint speech d'OpenAI. Vous pouvez également effectuer des appels HTTP standards avec votre clé API Bearer pour une intégration plus légère ou spécifique à votre langage de programmation.

Comment gérer le texte long ?

Le texte doit être divisé en parties de 4096 caractères maximum par requête. Vous devez ensuite assembler les fichiers audio générés pour chaque segment. Le SDK ou votre code doit gérer cette logique de segmentation et de concaténation des fichiers audio pour reconstituer le fichier final complet.

Faut-il segmenter manuellement ?

Oui, la limite est de 4096 caractères par requête API. Vous devez segmenter votre texte en amont ou utiliser une bibliothèque qui le fait automatiquement. Chaque segment déclenche une requête distincte et génère un fichier audio séparé que vous devrez ensuite joindre pour obtenir le résultat final.

Quelle voix choisir pour une news ?

Pour des nouvelles, la voix Atlas est recommandée. Elle est décrite comme neutre et adaptée à la lecture d'informations. Elle offre un ton clair et professionnel, idéal pour la restitution de contenu informatif sans apport émotionnel excessif, garantissant une écoute directe et factuelle pour vos auditeurs.

Comment éviter les timeouts ?

Les requêtes sont traitées séquentiellement et peuvent attendre dans une file d'attente en cas de charge. Pour les longs textes, prévoyez des timeouts plus larges. La génération est environ en temps réel (25 caractères/seconde). Augmentez le délai d'attente de votre client HTTP pour éviter les interruptions pendant le traitement.

Le streaming est-il possible ?

Non, le streaming ou le WebSocket n'est pas disponible. Vous recevez le fichier audio complet en réponse après sa génération. Le format de réponse est identique à celui d'OpenAI, retournant le fichier audio binaire une fois le traitement terminé. Il n'y a pas de flux audio partiel en temps réel.

Comment tester l'intégration ?

Inscrivez-vous sur /get-api-key/ pour obtenir une clé et un crédit d'essai initial. Utilisez l'exemple curl fourni sur le tableau de bord ou le SDK OpenAI avec l'URL de base modifiée. Envoyez une requête POST simple à /v1/audio/speech pour vérifier la réception du fichier audio.

Quelle est la latence moyenne ?

La vitesse est d'environ 25 caractères par seconde de texte généré. Les phrases courtes prennent quelques secondes. Les textes longs sont générés en temps réel approximatif. En cas de charge, les requêtes peuvent attendre dans une file d'attente avant d'être traitées séquentiellement par le moteur de synthèse.

Puis-je mettre en cache les réponses ?

Oui, vous pouvez mettre en cache les fichiers audio retournés. Les métadonnées de requête sont conservées pour la facturation, mais le fichier audio n'est pas stocké par le service. Si le texte, la voix et les paramètres sont identiques, vous pouvez réutiliser le fichier audio généré précédemment.

Comment gérer les erreurs de réseau ?

Si le paramètre language n'est pas défini, il est deviné selon le script (texte latin = anglais par défaut). Pour du texte latin non anglais, définissez explicitement le code ISO.

Faut-il gérer la détection de langue ?

Les voix sont des presets fixes basés sur des enregistrements licenciés. Il n'y a pas de clonage vocal personnalisé ni de conception de voix à la demande. Vous choisissez parmi les 8 presets disponibles (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion) qui restent constants dans leur ton et timbre.

Les voix sont-elles statiques ?

Créez un compte via /get-api-key/, rechargez votre solde en USDT (TRC-20) et utilisez votre clé API. Gérez la segmentation du texte (>4096 caractères) et les limites de taux (60 req/min). Implémentez la gestion des erreurs et le cache des réponses pour optimiser les coûts et la latence de votre application.

Comment passer en production ?

Le format MP3 est largement compatible. OPUS est également supporté et offre une bonne compression. WAV et FLAC sont disponibles pour une qualité sans perte mais prennent plus d'espace. PCM est brut. Choisissez MP3 pour un équilibre entre compatibilité et taille de fichier.

Choix de l'endpoint

Illustration d'onde sonore pour: Choix de l'endpoint

L'endpoint principal est POST /v1/audio/speech. Il accepte du texte brut et retourne un fichier audio. C'est l'action unique nécessaire pour convertir du texte en voix.

La requête utilise le format JSON standard. Elle inclut le modèle, le texte, la voix et le format souhaité. Une seule clé API suffit pour toutes les requêtes.

POST /v1/audio/speech

Envoyez vos requêtes à https://api.gogogold.top/v1/audio/speech. Cet endpoint unique génère l'audio synchronisé en réponse.

Conforme au standard OpenAI, il suffit de changer l'URL de base pour utiliser les SDKs officiels.

  • Endpoint unique pour la synthèse vocale
  • Réponse immédiate avec fichier audio

Format de la requête

Le corps de la requête doit être en JSON. Il contient les champs model, input, voice et response_format.

Le texte d'entrée (input) est limité à 4096 caractères par requête. Les espaces et ponctuation comptent.

  • JSON uniquement
  • Champ input limité à 4096 caractères

Authentification Bearer

Ajoutez l'en-tête Authorization: Bearer tts-... à chaque requête.

Une seule clé active par compte. Une nouvelle clé invalide l'ancienne immédiatement.

  • Clé API unique
  • En-tête Bearer standard

Configuration du SDK

Illustration d'onde sonore pour: Configuration du SDK

Pour intégrer notre API, modifiez simplement l'URL de base dans vos SDK OpenAI existants. Pointez base_url vers https://api.gogogold.top/v1. Cette approche permet de réutiliser le code standard tout en profitant de notre infrastructure.

Initialisez le client avec votre clé API unique. La gestion est simplifiée : une seule clé active par compte, révoquée instantanément lors de la régénération. Cela évite les conflits de sécurité lors des rotations.

Point de base

Changez l'URL de base du SDK pour inclure https://api.gogogold.top/v1. Cela redirige les appels vers notre endpoint POST /v1/audio/speech sans modifier la structure des payloads.

Les SDK officiels OpenAI fonctionnent en modifiant l'URL de base. Aucune librairie tierce spécifique n'est requise pour les appels HTTP standards.

Initialisation du client

Instanciez le client avec votre clé tts-... dans l'en-tête Authorization. Le code reste identique à l'usage standard du endpoint de speech.

Assurez-vous que votre clé est correctement chargée depuis vos variables d'environnement avant l'exécution des requêtes.

  • Utilisez des variables d'environnement pour stocker la clé.
  • Vérifiez la validité de la clé avant le premier appel.

Gestion des clés

Une seule clé active par compte. La régénération invalie immédiatement l'ancienne clé.

Ce modèle simplifie la sécurité : pas de gestion de permissions multiples ni de rotation complexe.

  • Clé unique par compte.
  • Révocation instantanée à la régénération.

Gestion des voix

Illustration d'onde sonore pour: Gestion des voix

L'API expose huit voix pré-enregistrées, issues de lectures publiques (LibriVox) et de fichiers audio sous licence CC BY 4.0. Chaque voix possède une signature acoustique distincte, optimisée pour des cas d'usage spécifiques, allant de la narration douce à la voix institutionnelle neutre.

La sélection se fait uniquement par le nom de la voix dans le champ voice de la requête JSON. Aucune personnalisation de timbre ou de vitesse n'est disponible au-delà du paramètre speed global (0.25–4.0).

Liste des voix

Huit voix sont disponibles : Aria, Nova, Luna, Sage, Felix, Milo, Atlas et Orion.

Chaque fichier audio généré contient un filigrane inaudible indiquant qu'il s'agit de parole synthétique.

  • Aria : voix féminine, narratrice chaleureuse et claire.
  • Nova : voix féminine, lumineuse et dynamique.
  • Luna : voix féminine, douce, idéale pour le storytelling.
  • Sage : voix féminine, calme, adaptée à l'instructionnel.
  • Felix : voix masculine, énergique, pour les promotions.
  • Milo : voix masculine, conversationnelle et amicale.
  • Atlas : voix masculine, neutre, style journal d'information.
  • Orion : voix masculine, profonde, style documentaire.

Choix selon le ton

Le choix de la voix doit anticiper l'usage final du contenu audio. Atlas convient pour des nouvelles brèves, tandis qu'Aria est préférable pour la lecture de livres audio.

Les voix ne supportent pas de tags d'émotion. Le ton est fixe ; seules la vitesse et la langue peuvent être ajustées via les paramètres de la requête.

Langues supportées

Les voix peuvent prononcer 23 langues, dont l'anglais, le français, l'espagnol, l'allemand, le japonais et l'arabe.

Le champ language est optionnel : le système devine la langue depuis la police de caractères (le texte latin non spécifié est traité comme de l'anglais). Il est recommandé de le définir explicitement pour les textes latins hors anglais.

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

Traitement du texte

Illustration d'onde sonore pour: Traitement du texte

L'API REST impose une contrainte stricte : chaque requête POST /v1/audio/speech ne peut contenir que 4096 caractères maximum, espaces et ponctuation inclus. Pour générer un contenu plus long, vous devez découper le texte en segments respectant cette limite avant l'envoi.

Chaque segment déclenche une synthèse indépendante. Le système ne stocke pas l'audio intermédiaire ; il le retourne immédiatement dans la réponse de l'endpoint. C'est à vous de gérer la séquence complète côté client ou serveur.

Découpe en segments

Divisez votre texte brut en blocs de 4096 caractères. Cette limite est matérielle ; tout texte supérieur à 4096 caractères dans le champ input génèrera une erreur immédiate.

Vous êtes responsable de la logique de segmentation. Assurez-vous de ne pas couper au milieu d'un mot si la cohérence phonétique est critique pour votre cas d'usage, bien que la synthèse gère généralement les coupures mot par mot.

  • La limite s'applique par requête, pas par session.
  • Les espaces et la ponctuation comptent dans les 4096 caractères.
  • Une requête échouée est gratuite, même si le texte dépasse la limite.

Limite 4096 caractères

Cette restriction s'applique à la fois au format texte brut et aux entrées JSON. Vérifiez la longueur de votre chaîne avant l'encodage JSON pour éviter les erreurs de validation.

Pour les textes très longs, cette limite implique que vous devrez effectuer plusieurs appels API successifs. Le coût sera calculé sur la somme totale des caractères traités dans tous les segments.

Concaténation audio

Une fois les segments synthétisés, vous devez les assembler pour créer le fichier audio final. L'API ne fournit pas de fonctionnalité de concaténation native ; c'est une opération côté client.

Utilisez une bibliothèque audio standard (comme FFmpeg ou une librairie langagière native) pour joindre les fichiers MP3, WAV, OPUS ou FLAC générés. Cette étape garantit que le flux audio final est continu et sans interruption audible entre les segments.

Assurez-vous que les formats audio retournés sont compatibles avec votre outil de concaténation pour éviter des artefacts de conversion supplémentaires.

  • Le format doit être identique pour tous les segments pour une concaténation directe.
  • L'audio est retourné dans le corps de la réponse, pas stocké en permanence.
  • La latence s'additionne : chaque segment ajoute un temps de génération.

Formats et compatibilité

Illustration d'onde sonore pour: Formats et compatibilité

Le format audio choisi affecte directement la taille des fichiers et la bande passante nécessaire. L'API accepte MP3, WAV, OPUS et FLAC pour le champ response_format.

Chaque format offre un compromis différent entre qualité, taille et compatibilité. Le choix dépend de l'usage final : diffusion web, stockage local ou traitement audio brut.

MP3 vs WAV

Le MP3 est recommandé pour la diffusion web grâce à son ratio compression/qualité. Le WAV offre une qualité brute sans perte, idéale pour les post-traitements.

La différence de taille est significative : un fichier WAV peut être jusqu'à dix fois plus lourd qu'un MP3 pour la même durée.

  • MP3 : compact, universel, recommandé pour le web.
  • WAV : qualité sans perte, fichiers plus volumineux.

OPUS pour la bande passante

Le format OPUS offre une compression efficace, réduisant la charge réseau tout en maintenant une bonne intelligibilité.

Idéal pour les applications mobiles ou les connexions à faible bande passante où la latence et l'utilisation de données sont critiques.

  • OPUS : compression élevée, idéal pour le mobile.

PCM brut

Le format PCM fournit des données audio non compressées et brutes.

Utilisez-le si vous devez traiter le signal audio directement sans décodage préalable, par exemple pour des analyses acoustiques précises.

  • PCM : données brutes, sans compression.

Gestion des erreurs

Illustration d'onde sonore pour: Gestion des erreurs

Lors de la génération d'audio, la fiabilité du pipeline dépend de la gestion précise des erreurs et des temps d'attente. Comme les requêtes sont traitées séquentiellement, une file d'attente peut se former en cas de charge, ce qui impacte la latence perçue.

Une intégration robuste doit anticiper les délais de réponse et distinguer clairement les échecs de synthèse des problèmes de réseau pour garantir une expérience utilisateur fluide, même lors des pics d'utilisation.

Retourner l'audio

L'API renvoie le fichier audio directement dans le corps de la réponse. En cas d'échec de la synthèse, aucun crédit n'est débité et la réponse indique clairement le statut de l'erreur pour permettre un traitement immédiat.

  • Vérifiez toujours le statut HTTP avant de parser le binaire.
  • Les erreurs de format ou de paramètres sont signalées immédiatement.

Gérer les timeouts

La vitesse de génération est d'environ une seconde par 25 caractères. Pour les textes longs, la requête peut prendre plusieurs secondes. Définissez un timeout client supérieur à 10 secondes pour éviter les coupures intempestives durant le traitement.

  • Augmentez le timeout pour les requêtes dépassant 1000 caractères.
  • Implémentez une logique de réessai avec backoff exponentiel pour les erreurs 503.

Rejouer les erreurs

Si une requête échoue en raison d'un problème réseau temporaire, revalidez la même entrée. Comme les requêtes échouées sont gratuites, le risque financier est nul. Priorisez la régularité du débit à la vitesse brute.

  • Réessayez les erreurs transitoires sans pénalité.
  • Ne pas réessayer les erreurs 400 (paramètres invalides).
Gestion des erreurs

Optimisation des coûts

Illustration d'onde sonore pour: Optimisation des coûts

La facturation repose strictement sur le volume de caractères envoyés, espaces et ponctuation inclus. Un seul appel peut traiter jusqu'à 4 096 caractères avant de nécessiter une nouvelle requête. Optimiser la longueur du texte d'entrée réduit directement le nombre d'appels API et, par conséquent, le coût final.

Compter les caractères

Vérifiez la longueur de votre chaîne avant l'envoi. Au-delà de 4 096 caractères, la requête échouera ou devra être découpée. Cette limite s'applique par appel, pas par session.

  • Espaces et ponctuation comptent comme des caractères.
  • 1 million de caractères = 10 USD.
  • Découpez manuellement si le texte dépasse la limite.

Réutiliser les clés

Une clé API unique gère tout votre volume. Il n'y a pas de frais par clé. Révoquez-la simplement si elle est compromise ; une nouvelle sera activée immédiatement, l'ancienne cessant de fonctionner instantanément.

  • Une seule clé par compte.
  • Révoquation immédiate lors du renouvellement.
  • Pas de coût lié à l'usage de la clé.

Surveiller le débit

La limite est de 60 requêtes par minute par clé (10 avant le premier rechargement). Un dépassement entraîne des erreurs temporaires. Surveillez vos logs pour ajuster la fréquence des appels en temps réel.

  • 60 requêtes/min par clé.
  • 10 requêtes/min en période de test.
  • Gérer les files d'attente pour éviter les 429.

Mise en production

Illustration d'onde sonore pour: Mise en production

La mise en production de votre intégration TTS repose sur une gestion rigoureuse des clés et une surveillance précise des requêtes. Chaque compte dispose d'une seule clé active ; une nouvelle révoque l'ancienne instantanément, ce qui simplifie la rotation sans complexité.

Clés de production

Utilisez une clé dédiée en production, distincte de celle de développement. Comme une nouvelle clé invalide l'ancienne immédiatement, planifiez la rotation pour éviter les interruptions de service lors du basculement.

  • Une seule clé active par compte
  • Révocation instantanée lors de la génération d'une nouvelle clé

Monitoring des requêtes

Surveillez le taux d'erreur et le temps de génération. Les requêtes s'exécutent séquentiellement ; une file d'attente peut survenir en cas de charge forte, augmentant la latence perçue pour les phrases courtes.

Tests de charge

Vérifiez la limite de 60 requêtes par minute. Assurez-vous que votre logique de découpe du texte (segments de 4096 caractères) et la concaténation audio restent stables sous cette contrainte de débit.

Cas pratique

Illustration d'onde sonore pour: Cas pratique

Ces cas d'usage illustrent l'intégration concrète de l'API dans des workflows variés, de la narration longue aux alertes immédiates.

Lecture d'articles

Pour les blogs ou les news, découpez le texte en segments de 4096 caractères. Envoyez-les via POST /v1/audio/speech avec voice: aria pour un ton narratif clair.

  • Utilisez speed: 1.0 pour une lecture naturelle.
  • Concaténez les fichiers MP3 retournés pour créer un audio continu.

Notifications sonores

Pour les alertes système, privilégiez voice: felix ou nova. Les phrases courtes prennent quelques secondes à générer. Le format MP3 assure une compatibilité universelle.

  • Limitez le texte pour réduire la latence perçue.
  • Testez les temps de génération avec des phrases de moins de 100 caractères.

Livres audio

Pour les contenus longs, utilisez voice: luna ou atlas. Le traitement par lots permet de générer des heures de contenu. Le coût est de 0,01 $ par 1 000 caractères.

  • Respectez la limite de 60 requêtes par minute.
  • Surveillez la file d'attente pour les gros volumes.

Dépannage courant

Illustration d'onde sonore pour: Dépannage courant

Lors de l'intégration de l'API TTS, les erreurs courantes peuvent interrompre le flux audio si elles ne sont pas anticipées. Voici les trois cas les plus fréquents et leur résolution immédiate.

Ces vérifications simples suffisent à résoudre la majorité des blocages techniques avant la mise en production.

Erreur 401

Un code 401 indique que la clé API est manquante, invalide ou expirée. Vérifiez l'en-tête Authorization: Bearer tts-... dans votre requête.

Si vous avez révoqué une clé, l'ancienne devient inactive immédiatement. Utilisez uniquement la clé active affichée dans votre tableau de bord.

  • Vérifiez la présence du préfixe Bearer.
  • Confirmez que la clé n'a pas été révoquée récemment.

Limites de débit

Vous atteignez la limite de 60 requêtes par minute. Attendez que le compteur se réinitialise ou réduisez la fréquence de vos appels.

Avant votre premier rechargement, la limite est de 10 requêtes/minute. Un rechargement via USTR augmente instantanément votre quota.

  • Implémentez une file d'attente côté client.
  • Espacez les appels courts pour éviter les blocages.

Format non supporté

Seuls mp3, wav, opus, flac et pcm sont acceptés. Une demande avec un format inconnu renverra une erreur immédiate.

Assurez-vous que votre texte ne dépasse pas 4096 caractères. Pour les textes plus longs, découpez-les et concaténez les fichiers audio générés.

  • Utilisez GET /v1/voices pour valider les formats.
  • Testez d'abord avec un texte court.

Bonnes pratiques

Illustration d'onde sonore pour: Bonnes pratiques

Pour une intégration fluide, il est essentiel de comprendre que les requêtes sont traitées séquentiellement. En cas de charge élevée, une file d'attente peut s'installer, augmentant la latence globale sans impacter le prix facturé par caractère.

Gestion de la file d'attente

Les requêtes s'empilent et s'exécutent une par une. En cas de forte sollicitation, l'attente peut dépasser le temps de génération réel. Prévoyez des timeouts larges dans votre client HTTP et évitez les appels en boucle serrée sans intervalle.

  • Utilisez des backoffs exponentiels pour les appels parallèles.
  • Surveillez les temps de réponse pour détecter l'encombrement.

Latence perçue

Les phrases courtes prennent quelques secondes à générer, ce qui peut sembler long pour l'utilisateur. Pour les textes longs, le débit est proche du temps réel (25 caractères/seconde). Affichez un indicateur de chargement pertinent pour masquer la latence initiale.

Caching des audio courts

Stockez en cache les fichiers audio pour les phrases récurrentes (boutons, messages d'erreur). Cela réduit le nombre de requêtes API, économise votre solde et diminue la latence perçue. Notez que les fichiers générés ne sont pas stockés sur nos serveurs.

Écoutez les 8 voix

Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. L'audio généré est retourné dans la réponse et n'est pas stocké sur nos serveurs après la livraison.

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. OpenAI API reference: create speech
  3. openai-python on GitHub
  4. Python documentation
  5. Tether (USDT)
  6. TRON developer hub: TRC-20
  7. Node.js documentation
  8. ISO 639 language codes
  9. W3C WAI: making audio and video accessible
  10. LibriTTS-R corpus (OpenSLR 141)
  11. MDN: Web Speech API
  12. FFmpeg documentation

Plus sur ce site