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
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
inputlimité à 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
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
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
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é
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
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).

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
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
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.0pour 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
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/voicespour valider les formats. - Testez d'abord avec un texte court.
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.
23 langues
Chaque voix peut parler n'importe laquelle de ces langues.
