Documentation technique de l'API de synthèse vocale

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

Cette documentation détaille l'intégration de l'API REST ParoleVive, conçue spécifiquement pour les développeurs indie et les startups qui intègrent une voix synthétique dans leurs produits. Vous y trouverez les spécifications techniques nécessaires pour convertir du texte en audio via des appels HTTP standard, sans dépendance à un SDK propriétaire.

Vous apprendrez à obtenir votre clé API, à formater vos requêtes JSON et à gérer les formats de sortie comme le MP3 ou le WAV. Les sections couvrent également les limites de débit, la gestion des erreurs et les exemples concrets pour les textes longs, garantissant une mise en œuvre fiable et économique.

Documentation technique de l'API de synthèse vocale

Questions fréquentes

Comment obtenir une clé API ?

Inscrivez-vous sur la page /get-api-key/ via Google ou email. Vous recevrez une clé Bearer unique. Vous pouvez en générer une nouvelle à tout moment ; l’ancienne devient inactive immédiatement. La page affiche également votre solde et un exemple curl prêt à l’emploi pour commencer.

Quelle est la structure du corps JSON ?

Envoyez un POST à /v1/audio/speech avec un corps JSON contenant les champs requis. La structure suit exactement le format de l’endpoint OpenAI Speech. Utilisez les SDK officiels OpenAI en modifiant simplement l’URL de base vers https://api.gogogold.top/v1 pour une intégration transparente.

Puis-je utiliser le SDK Python d'OpenAI ?

Oui, les SDK officiels OpenAI fonctionnent parfaitement. Il suffit de changer l’URL de base (base_url) vers https://api.gogogold.top/v1 et d’utiliser votre clé ParoleVive. La forme de la requête est identique à celle de l’endpoint Speech d’OpenAI, garantissant une compatibilité immédiate.

Quels sont les champs obligatoires ?

Les champs obligatoires sont model, input et voice. model accepte 'tts-1' ou 'tts-1-hd'. input contient le texte (max 4096 caractères). voice doit être l’un des 8 presets disponibles. response_format et speed sont optionnels mais recommandés pour contrôler le format audio et la vitesse de lecture.

Comment spécifier une langue ?

Utilisez le champ optionnel language avec un code ISO. Si absent, la langue est déduite du script (le texte latin par défaut en anglais). Pour les textes latins non anglais, définissez explicitement language. Les 23 langues supportées incluent le français, l’espagnol et l’allemand, mais pas l'ukrainien ou le thaï.

Quelle est la limite de caractères ?

Chaque requête est limitée à 4096 caractères. Pour les textes plus longs, divisez-les en parties respectant cette limite et joignez les fichiers audio générés. Les espaces et la ponctuation comptent comme des caractères dans ce décompte. Cette contrainte s’applique à chaque appel API individuel.

Que se passe-t-il en cas de dépassement ?

Le serveur peut rejeter la requête si le texte dépasse 4096 caractères. Vous devez fractionner votre texte en plusieurs requêtes de 4096 caractères maximum. Assemblées, les réponses audio forment le fichier final. Aucun crédit n’est perdu pour ce rejet, car il s’agit d’une erreur de format ou d’un échec de synthèse.

Les fichiers audio sont-ils stockés ?

Non, les fichiers audio générés sont retournés dans la réponse immédiate et ne sont pas stockés par nos soins. Seul le texte d’entrée est utilisé pour la synthèse. Les métadonnées de la requête (heure, caractères, statut) sont conservées uniquement pour la facturation et la traçabilité.

Comment révoquer une clé ?

Générez une nouvelle clé depuis votre tableau de bord sur /get-api-key/. L’ancienne clé devient inactive immédiatement dès la génération de la nouvelle. Vous n’avez pas besoin de notifier vos clients si vous changez de clé, car l’ancienne cesse de fonctionner instantanément.

Le format PCM est-il supporté ?

Oui, le format PCM est parmi les formats supportés, aux côtés de mp3, wav, opus et flac. Spécifiez simplement 'pcm' dans le champ response_format de votre requête JSON. Cela permet d’obtenir un fichier audio brut non compressé, utile pour certains pipelines de traitement audio spécifiques.

Quelle erreur renvoie une clé invalide ?

Une clé invalide ou manquante entraîne généralement une erreur d’authentification (401 Unauthorized). Vérifiez que votre en-tête Authorization contient bien 'Bearer tts-...'. Assurez-vous également que la clé n’a pas été révoquée.

La vitesse doit-elle être un entier ?

Non, le champ speed accepte des valeurs décimales entre 0.25 et 4.0. Vous pouvez ajuster la vitesse avec précision pour adapter la synthèse à vos besoins. La valeur par défaut est généralement 1.0. Toute valeur hors de cette plage sera rejetée par l’API.

Comment gérer les requêtes en file d'attente ?

Les requêtes sont traitées séquentiellement. En cas de charge, une requête peut attendre dans une file d’attente. Pour les longs textes, la génération prend environ le temps réel de lecture. Implémentez une logique de retry avec backoff pour gérer les délais potentiels lors des pics de trafic.

Première requête

curl

curl https://api.gogogold.top/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.gogogold.top/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.gogogold.top/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 une clé API

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

Accédez à la page /get-api-key/ pour initialiser votre compte. L'interface affiche votre clé API unique, le solde disponible (incluant le crédit d'essai de 0,50 $ pour les inscriptions Google) ainsi que l'exemple cURL prêt à l'emploi.

Page de configuration

Page de configuration

La page de configuration centralise les informations essentielles : clé active, solde restant et historique d'utilisation. Elle sert de point de départ pour toute intégration, sans nécessiter de formulaire supplémentaire.

Génération de clé

Génération de clé

Une seule clé active est attribuée par compte. Elle se présente sous la forme tts-... et s'utilise via l'en-tête Authorization: Bearer dans vos requêtes HTTP.

Révocation immédiate

Vous pouvez générer une nouvelle clé à tout moment. L'ancienne clé devient invalide instantanément, assurant une sécurité maximale en cas de fuite ou de changement d'environnement de développement.

Première requête

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

Une fois votre clé obtenue, envoyez une requête POST à l'endpoint https://api.gogogold.top/v1/audio/speech. Le corps de la requête doit contenir le texte à synthétiser, le modèle choisi et la voix cible. Le service traite les requêtes séquentiellement ; en cas de charge, votre demande peut attendre dans une file d'attente avant génération.

L'API répond par un fichier audio binaire. Pour les textes longs, segmentez votre texte en blocs de 4096 caractères maximum et joignez les fichiers audio générés. La vitesse de génération est approximativement de 25 caractères par seconde pour des textes longs, bien que les phrases courtes prennent quelques secondes.

Exemple cURL

Exécutez cette commande pour tester l'endpoint. Remplacez VOTRE_CLE par votre clé API réelle.

La réponse contient le fichier audio binaire directement dans le corps de la réponse HTTP.

  • curl -X POST https://api.gogogold.top/v1/audio/speech \
  • -H "Authorization: Bearer VOTRE_CLE" \
  • -H "Content-Type: application/json" \
  • ` -d '{"model": "tts-1", "input": "Bonjour", "voice": "nova", "response_format": "mp3"}'`

Corps JSON

Le corps de la requête est un objet JSON standard. Le champ input accepte jusqu'à 4096 caractères. Les espaces et la ponctuation comptent comme des caractères. Le modèle tts-1-hd utilise le même moteur et le même prix que tts-1. Le champ voice doit correspondre à l'une des 8 voix disponibles, comme aria, nova ou atlas.

Vous pouvez optionnellement définir le language avec un code ISO pour éviter l'inférence automatique, surtout pour les textes en latin autre que l'anglais. Le champ speed varie de 0.25 à 4.0 pour ajuster la vitesse de lecture.

Réponse audio

En cas de succès, l'API retourne le fichier audio au format demandé (mp3, wav, opus, flac ou pcm). Aucune donnée audio n'est stockée ; elle est retournée uniquement dans la réponse. En cas d'échec de la synthèse, aucun frais n'est appliqué et le solde est intégralement remboursé. Les fichiers générés comportent un filigrane inaudible marquant le contenu comme synthétique.

SDK OpenAI

Illustration d'onde sonore pour: SDK OpenAI

L'API ParoleVive suit le même format de requête que l'endpoint OpenAI Speech. Cela permet aux développeurs d'utiliser les SDK officiels OpenAI sans réécrire leur logique d'intégration.

Il suffit de modifier l'URL de base (base_url) vers https://api.gogogold.top/v1 et d'injecter la clé API ParoleVive. Les modèles tts-1 et tts-1-hd sont compatibles.

Changement de base_url

Pointez simplement le client vers https://api.gogogold.top/v1 au lieu du endpoint OpenAI par défaut. Cette modification suffit pour rediriger tous les appels vers notre infrastructure.

La structure JSON du corps de la requête reste identique, garantissant une migration transparente pour vos projets existants.

  • Base URL: https://api.gogogold.top/v1
  • Endpoint: /v1/audio/speech
  • Authentification: Bearer <votre_clé>

Utilisation des clients

Installez le package standard de l'OpenAI SDK pour votre langage préféré. Initialisez le client en spécifiant uniquement l'API key et la nouvelle base URL.

Appellez la méthode audio.speech.create() avec vos paramètres habituels (modèle, voix, input). Le SDK gérera l'encodage et l'envoi du fichier audio.

Compatibilité

Les SDK officiels OpenAI fonctionnent en modifiant l'URL de base (base_url).

Les formats de réponse audio (mp3, wav, opus, flac, pcm) sont retournés tels quels, prêts à être lus ou stockés.

Paramètres de requête

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

Les paramètres de requête définissent le comportement de la synthèse. Chaque champ modifie directement le rendu audio ou le moteur utilisé pour la génération.

La configuration par défaut convient à la plupart des cas, mais les développeurs peuvent ajuster le modèle, la voix et la vitesse pour s'adapter à leur flux de travail.

Champ model

Ce champ accepte deux valeurs : "tts-1" ou "tts-1-hd". Les deux utilisent le même moteur de synthèse vocale et sont facturés au même tarif.

Le choix n'affecte pas le prix ni la qualité perçue dans la plupart des scénarios standards. Sélectionnez celui qui correspond à vos préférences techniques.

Champ voice

Vous devez spécifier l'une des 8 voix prédéfinies disponibles via l'endpoint /v1/voices. Le choix dépend du ton souhaité pour votre contenu.

Les voix incluent des options féminines (Aria, Nova, Luna, Sage) et masculines (Felix, Milo, Atlas, Orion). Chaque voix possède un caractère distinct, allant du narrateur clair au ton documentaire profond.

  • Aria : narratrice chaleureuse et claire
  • Atlas : voix neutre adaptée aux nouvelles

Champ speed

Le paramètre speed permet de modifier la vitesse de lecture entre 0.25 et 4.0. La valeur par défaut est 1.0.

Augmenter la vitesse réduit le temps de génération et la durée du fichier audio. Une vitesse trop élevée peut affecter la clarté de la parole synthétique.

Formats de sortie

Illustration d'onde sonore pour: Formats de sortie

Le format audio est spécifié via le champ response_format dans le corps JSON de la requête. Quatre options sont disponibles, chacune optimisée pour des cas d'usage différents, de la compression standard à la qualité sans perte.

Le choix du format impacte la taille des fichiers reçus et leur compatibilité immédiate avec vos lecteurs ou services de stockage. Toutes les voix génèrent ces formats sans perte de qualité vocale intrinsèque.

MP3

Format par défaut, universellement compatible avec la plupart des lecteurs et plateformes web. Idéal pour les applications mobiles et les sites web standards où la bande passante doit être optimisée sans sacrifice majeur de l'audibilité.

WAV

Audio non compressé, préservant la qualité brute du signal. Utiliser ce format augmente considérablement la taille des fichiers stockés ou transmis, mais garantit une fidélité audio maximale pour les traitements audio en aval ou les enregistrements professionnels.

OPUS et FLAC

OPUS offre une compression efficace avec une excellente qualité à faible débit binaire, tandis que FLAC fournit une compression sans perte. Ces formats sont choisis pour des besoins spécifiques de qualité audio ou d'archivage, selon que vous privilégiez le ratio compression/qualité ou l'intégrité parfaite des données.

Formats de sortie

Limites et quotas

Illustration d'onde sonore pour: Limites et quotas

L'API ParoleVive applique une limite stricte de 60 requêtes par minute par clé API. Ce quota s'applique au point d'entrée /v1/audio/speech et couvre toutes les tentatives, qu'elles aboutissent ou échouent. Cette contrainte est conçue pour garantir une stabilité du service sans nécessiter de gestion manuelle des tokens.

60 requêtes par minute

Chaque clé active est limitée à 60 appels API par minute. Cette limite est globale et ne varie pas selon le plan de facturation. Elle s'applique uniformément, que vous utilisiez le modèle tts-1 ou tts-1-hd.

Limite avant premier dépôt

Pour les nouveaux comptes sans solde chargé, le débit est réduit à 10 requêtes par minute. Cette restriction s'applique automatiquement dès la création de la clé. Elle est levée dès la réception du premier dépôt USDT (TRC-20) (minimum 5 $).

Gestion du file d'attente

Les requêtes excédant la limite ne sont pas rejetées immédiatement. Elles sont placées en file d'attente et traitées séquentiellement. Pour les textes longs, le traitement est linéaire : la génération prend environ le temps réel de l'audio. En cas de forte charge, le délai d'attente augmente proportionnellement au nombre de requêtes en attente.

Gestion des erreurs

Illustration d'onde sonore pour: Gestion des erreurs

Une requête échouée ne consomme pas de crédit. Le solde reste intact et aucune charge n'est appliquée, ce qui garantit que les erreurs de réseau ou de format ne pénalisent pas votre budget. Vous pouvez réessayer sans crainte de perte financière.

En cas d'erreur, l'API retourne un code HTTP approprié et un message explicite. Il suffit de vérifier la syntaxe du JSON ou la validité de la clé dans l'en-tête Authorization.

Codes d'erreur courants

Les erreurs 4xx indiquent généralement une mauvaise requête (clé invalide, modèle inconnu). Les erreurs 5xx sont rares et signalent un problème temporaire du service. Consultez la documentation pour la liste complète des codes retournés lors d'un échec de synthèse.

  • 401 : Clé API invalide ou manquante
  • 400 : Corps JSON incorrect ou texte vide
  • 429 : Limite de débit dépassée (60 req/min)

Requêtes échouées

Si la synthèse échoue (par exemple, problème moteur interne), le caractère n'est pas décompté. Le statut de la requête reflète cet échec sans impact sur votre solde. Vous pouvez réessayer immédiatement.

Retour de solde

Votre solde est mis à jour en temps réel après chaque requête aboutie. En cas d'échec, aucune déduction n'est effectuée. Vérifiez votre tableau de bord pour confirmer le solde restant et l'historique des transactions.

Exemples avancés

Illustration d'onde sonore pour: Exemples avancés

Ces exemples couvrent les cas d'usage courants : forcer une langue, ajuster le débit et gérer les longs textes. Ils illustrent la flexibilité de l'API pour des intégrations précises.

Langue spécifique

Par défaut, l'API devine la langue (anglais pour le latin). Pour forcer le français ou l'allemand avec des caractères latins, utilisez le champ language dans le corps JSON.

  • Exemple : `{ "model": "tts-1", "input": "Bonjour", "voice": "nova", "language": "fr" }`

Vitesse personnalisée

Le champ speed accepte une valeur entre 0.25 et 4.0. La valeur par défaut est 1.0. Cela permet d'adapter le rythme de lecture au contexte de votre application.

Texte long segmenté

L'API limite l'entrée à 4 096 caractères. Pour les textes plus longs, divisez-les en segments, envoyez-les séquentiellement, puis assemblez les fichiers audio résultants côté client ou serveur.

É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. MDN: Web Speech API
  4. Tether (USDT)
  5. openai-node on GitHub
  6. ISO 639 language codes
  7. TRON developer hub: TRC-20
  8. Python documentation
  9. IETF RFC 7845: Ogg Opus
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. LibriVox public-domain audiobooks
  12. FFmpeg documentation

Plus sur ce site