Guide d'intégration API TTS pour développeurs

Par L'équipe VoixOff Studio · Mis à jour 2026-11-18

Cette documentation explique comment intégrer notre API Text-to-Speech dans vos projets de jeux vidéo. Vous apprendrez à générer des voix pour vos NPC et interfaces en quelques minutes, avec des exemples concrets en cURL, Python et JavaScript.

Nous nous adressons aux développeurs indépendants et aux startups qui ont besoin d’une solution fiable et économique. Chaque section détaille les endpoints, les paramètres de voix et les bonnes pratiques pour intégrer l'audio dans vos moteurs de jeu.

Guide d'intégration API TTS pour développeurs

Questions fréquentes

Quelle est la limite de caractères ?

Chaque requête accepte jusqu'à 4096 caractères. Les espaces et la ponctuation comptent dans ce total. Pour les textes plus longs, vous devez les diviser en plusieurs parties de 4096 caractères maximum et joindre les fichiers audio générés.

Comment utiliser le SDK OpenAI ?

Modifiez l'URL de base du SDK OpenAI vers https://api.getth39.com/v1. Utilisez votre clé API VoixOff Studio avec la méthode standard. La structure de la requête est identique à celle de l'endpoint de parole d'OpenAI.

Quels formats audio sont supportés ?

Vous pouvez choisir entre mp3, wav, opus, flac et pcm via le champ response_format. Ces formats s'appliquent aux modèles tts-1 et tts-1-hd. Le format par défaut est généralement le mp3 pour une compatibilité large.

Comment changer la vitesse de parole ?

Utilisez le paramètre speed dans votre requête JSON, avec une valeur comprise entre 0,25 et 4,0. La valeur par défaut est 1,0. Cela permet d'accélérer ou de ralentir la voix sans altérer le ton.

Comment obtenir une clé API ?

Inscrivez-vous sur la page /get-api-key/ en utilisant Google ou un e-mail. Votre clé API sera affichée directement sur cette page après la connexion. Elle commence par tts- et s'utilise via l'en-tête Authorization.

Que faire en cas d'erreur ?

Les requêtes échouées sont gratuites et le montant est remboursé intégralement. Vérifiez simplement que votre texte respecte la limite de 4096 caractères et que votre solde est suffisant. Le format JSON doit être valide.

Quelle est la limite de requêtes par minute ?

Vous disposez de 60 requêtes par minute par clé API. Avant le premier rechargement, cette limite est de 10 requêtes par minute. Respectez ces limites pour éviter les retards de traitement.

Les voix sont-elles personnalisables ?

Non, vous choisissez parmi 8 presets fixes (comme Aria, Nova, Felix). Il n'y a pas de clonage vocal personnalisé ni de modification des paramètres vocaux au-delà de la vitesse. Les voix sont basées sur des enregistrements licenciés.

Comment gérer les longs textes ?

Découpez votre texte en segments de 4096 caractères ou moins. Envoyez chaque segment via une requête distincte. Une fois les fichiers audio reçus, assemblez-les dans votre moteur de jeu ou votre application pour obtenir le résultat final.

Y a-t-il une documentation technique ?

Oui, cette page documente l'intégration. L'API suit le format OpenAI. Consultez les endpoints /v1/audio/speech et /v1/voices pour les détails. La structure JSON est standardisée pour faciliter l'utilisation avec les SDK existants.

Les requêtes sont-elles synchrones ?

Oui, vous envoyez du texte et recevez directement le fichier audio dans la réponse. Cependant, le traitement peut prendre du temps selon la file d'attente. La génération est approximativement à vitesse réelle pour les textes longs.

Comment tester l'API ?

Utilisez la page /get-api-key/ pour obtenir votre clé et un exemple de commande curl prêt à l'emploi. Vous pouvez également tester via le SDK OpenAI en changeant simplement l'URL de base vers notre API.

Y a-t-il un exemple de code ?

La page /get-api-key/ fournit un exemple de commande curl. Vous pouvez également utiliser le SDK Python ou Node.js d'OpenAI en pointant l'URL de base vers https://api.getth39.com/v1.

Comment révoquer une clé API ?

Générez une nouvelle clé depuis votre tableau de bord sur /get-api-key/. L'ancienne clé devient inactive instantanément dès la génération de la nouvelle. Vous pouvez ainsi révoquer l'accès immédiatement sans délai.

Première requête

curl

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

Obtenir votre clé API

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

Pour utiliser l'API, créez un compte sur /get-api-key/ via Google ou email. La clé API s'affiche immédiatement. Elle commence avec "tts-" et sert à authentifier vos requêtes.

Création de compte et génération de clé

Création de compte et génération de clé

Accédez à la page d'inscription et choisissez Google ou email/mot de passe. Un compte par site est créé. La clé est visible instantanément dans votre tableau de bord.

Authentification Bearer

Authentification Bearer

Envoyez votre clé dans l'en-tête HTTP. Utilisez le format : Authorization: Bearer tts-votre-clé. C'est le seul moyen d'identifier votre compte et de débiter votre solde.

Gestion des clés et révoquation

Une seule clé active par compte. Émettez-en une nouvelle à tout moment. L'ancienne devient invalide immédiatement. Révoquez simplement en générant la nouvelle.

Première requête : cURL

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

Pour tester rapidement votre intégration, utilisez cURL. Cette méthode simple permet de vérifier que votre clé fonctionne et que le flux de génération audio s'exécute correctement avant d'implémenter la logique dans votre moteur de jeu.

Exemple de commande cURL

Exécutez cette commande en remplaçant VOTRE_CLE et VOTRE_VOIX par vos propres valeurs. L'endpoint POST https://api.getth39.com/v1/audio/speech attend un corps JSON standard.

Envoi du texte et du modèle

Le corps de la requête JSON contient le texte à synthétiser dans le champ input. Vous pouvez choisir entre tts-1 ou tts-1-hd via le champ model. Les deux utilisent le même moteur et le même prix.

Réponse avec fichier audio

Le serveur retourne le fichier audio binaire directement dans la réponse. Pour vos NPCs, sauvegardez simplement ce flux dans un fichier temporaire ou chargez-le directement en mémoire dans votre moteur (Unity, Godot, Unreal) pour une lecture immédiate.

Utilisation avec le SDK OpenAI

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

L'API est conçue pour être directement compatible avec les SDK officiels OpenAI, ce qui simplifie l'intégration dans vos pipelines existants. Il suffit de modifier l'URL de base pour pointer vers notre infrastructure tout en conservant la même structure de requête JSON.

Cette approche vous permet d'utiliser les bibliothèques familiarisées sans réécrire votre logique de génération audio, en adaptant simplement l'endpoint et la clé API.

Modification de la base URL

Pour utiliser nos services avec le SDK OpenAI, pointez simplement la variable base_url vers https://api.getth39.com/v1. Cela redirige toutes les requêtes vers notre endpoint POST /v1/audio/speech tout en maintenant la compatibilité avec les formats d'entrée et de sortie standards.

Assurez-vous d'utiliser votre clé API VoixOff Studio (préfixée par tts-...) dans l'en-tête Authorization: Bearer. La structure du corps de la requête reste identique à celle d'OpenAI : model, input, voice, response_format et speed.

  • Endpoint : https://api.getth39.com/v1
  • Authentification : Bearer tts-...

Compatibilité avec les SDK officiels

Les SDK OpenAI (Python, Node.js, etc.) fonctionnent immédiatement sans modification de code majeure, car la forme du corps JSON est la même. Vous pouvez ainsi générer de l'audio en utilisant les méthodes Audio standard du SDK.

Cette compatibilité signifie que vous n'avez pas besoin d'apprendre une nouvelle syntaxe d'API. Vous bénéficiez de la robustesse des bibliothèques OpenAI tout en profitant de nos tarifs et de nos voix.

Notez que nous ne fournissons pas notre propre SDK dédié ; l'utilisation du SDK OpenAI est la méthode recommandée pour une intégration rapide et fiable dans vos projets.

Exemple de code Python/JS

Voici un exemple minimal en Python pour générer un fichier audio. Il utilise le SDK openai en redirigeant simplement la base URL vers notre service.

```python from openai import OpenAI client = OpenAI( api_key="tts-votre-cle-ici", base_url="https://api.getth39.com/v1" ) audio = client.audio.speech.create( model="tts-1", voice="aria", input="Bienvenue dans votre jeu !", response_format="mp3" ) with open("output.mp3", "wb") as f: f.write(audio.content) ```

L'exemple JavaScript suit la même logique en initialisant la bibliothèque openai avec l'URL de base correcte. Cette approche garantit que vos scripts de génération de voix pour les NPCs s'intègrent sans friction dans vos boucles de développement.

Modèles et formats audio

Illustration d'onde sonore pour: Modèles et formats audio

La seule différence entre les modèles tts-1 et tts-1-hd réside dans le modèle de synthèse utilisé ; le prix reste identique pour les deux. Vous pouvez donc basculer d'un modèle à l'autre sans surcoût, selon vos besoins en qualité ou en latence pour vos NPCs.

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

Utilisez tts-1 pour un équilibre standard entre vitesse et qualité, ou tts-1-hd pour une synthèse légèrement plus riche. Les deux modèles supportent les 8 voix preset et les 23 langues listées, avec une limite de 4096 caractères par requête.

Formats : MP3, WAV, OPUS, FLAC, PCM

L'API retourne l'audio sous forme binaire. Vous pouvez choisir entre MP3, WAV, OPUS, FLAC ou PCM. Le format MP3 est recommandé pour la plupart des usages web et mobiles grâce à sa compression efficace.

  • MP3 : Compression standard, idéal pour le web.
  • WAV : Audio non compressé, qualité brute.
  • OPUS : Haute efficacité, faible poids.
  • FLAC : Compression sans perte.
  • PCM : Données brutes non encodées.

Choix du format selon l'usage

Pour un jeu vidéo, privilégiez le MP3 ou l'OPUS pour réduire la taille des assets et accélérer les chargements. Le format WAV ou FLAC convient mieux si vous avez besoin d'une qualité audio maximale pour des séquences cinématiques, au prix d'un stockage plus élevé.

Paramètres de la voix et de la vitesse

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

La qualité vocale impacte directement l'immersion de vos personnages et interfaces. Nous proposons huit presets, allant du narrateur clair aux voix énergiques pour les promos.

Sélection des 8 voix preset

Choisissez parmi quatre voix féminines (Aria, Nova, Luna, Sage) et masculines (Felix, Milo, Atlas, Orion). Chaque voix offre une tonalité distincte, idéale pour différencier vos NPC ou générer des annonces claires.

  • Aria : Narratrice chaleureuse et claire
  • Nova : Voix lumineuse et dynamique
  • Felix : Énergique, idéal pour les promos

Contrôle de la vitesse (0.25 à 4.0)

Ajustez le paramètre speed pour adapter le débit de parole à l'action en jeu. Une vitesse réduite (0.25) convient aux dialogues introspectifs, tandis qu'un débit élevé (4.0) accélère les instructions techniques sans altérer la clarté.

Spécification de la langue

Par défaut, le système devine la langue via l'alphabet (le latin par défaut en anglais). Pour garantir une prononciation exacte en français, allemand ou japonais, définissez explicitement le paramètre language avec le code ISO approprié.

Paramètres de la voix et de la vitesse

Limites et gestion des erreurs

Illustration d'onde sonore pour: Limites et gestion des erreurs

Pour garantir la fiabilité de la synthèse, chaque requête est limitée à 4096 caractères. Le texte dépasse cette limite doit être découpé en plusieurs appels et les fichiers audio résultants assemblés ensuite.

Limite de 4096 caractères par requête

Chaque appel API accepte un maximum de 4096 caractères pour le champ input. Cette contrainte s'applique au texte brut envoyé, espaces et ponctuation inclus. Pour les dialogues longs de vos NPC, découpez le texte et concaténez les fichiers audio retournés.

Gestion des erreurs courantes

En cas d'échec de la synthèse, la demande est gratuitement créditée. Le solde est intégralement remboursé sans action manuelle de votre part. Vérifiez toujours le code de statut HTTP pour confirmer la réussite ou l'échec de la génération.

Taux de limite (60 req/min)

Chaque clé API est limitée à 60 requêtes par minute. Avant le premier rechargement de compte, le plafond est réduit à 10 requêtes par minute. Respectez ces limites pour éviter les erreurs 429 et les attentes en file d'attente.

  • 60 req/min pour les comptes rechargés
  • 10 req/min avant premier rechargement
  • Gestion automatique de la file d'attente

Endpoints disponibles

Illustration d'onde sonore pour: Endpoints disponibles

Les endpoints REST de VoixOff Studio sont conçus pour une intégration directe dans les moteurs de jeu. L'endpoint principal génère l'audio, tandis que les points de terminaison secondaires fournissent les métadonnées nécessaires au runtime du jeu.

POST /v1/audio/speech

Point d'entrée principal. Il accepte du texte JSON et renvoie un fichier audio binaire. Le corps de la requête suit le format OpenAI (modèle, entrée, voix, format, vitesse).

GET /v1/voices

Liste les 8 voix disponibles, les langues supportées et les formats audio. Cet endpoint permet de dynamiser l'interface utilisateur de votre jeu pour la sélection de voix.

GET /v1/models

Retourne les modèles disponibles (tts-1 et tts-1-hd). Utile pour vérifier la disponibilité des capacités de synthèse avant de lancer un batch de génération.

Bonnes pratiques pour les jeux

Illustration d'onde sonore pour: Bonnes pratiques pour les jeux

Pour les jeux, une voix unique peut vite lassier. Avec huit voix et des vitesses ajustables de 0.25 à 4.0, vous pouvez varier le ton des PNJ et créer une atmosphère plus vivante sans effort supplémentaire.

Gérez les files d'attente en comprenant que les demandes sont traitées séquentiellement. En cas de charge, les requêtes peuvent attendre avant génération, ce qui impacte le temps de réponse immédiat.

Découpage des longs textes

Limitez chaque requête à 4 096 caractères. Pour les dialogues plus longs, découpez votre texte, générez chaque segment puis assemblez les fichiers audio dans votre moteur.

Le format OPUS ou FLAC est recommandé pour préserver la qualité lors de l'assemblage, bien que le MP3 soit plus léger.

  • Respectez la limite stricte de 4096 caractères par appel POST.
  • Assemblez les fichiers générés pour reconstituer le dialogue complet.

Gestion des files d'attente

Les demandes sont traitées une par une. En période de forte activité, une file d'attente peut se former, ralentissant la génération.

Prévoyez un délai de latence supplémentaire dans votre logique de jeu pour éviter les blocages visuels pendant le chargement audio.

  • Taux de limite : 60 requêtes par minute par clé API.
  • Le traitement séquentiel peut créer des délais sous charge.

Optimisation des appels API

Utilisez le format PCM pour une intégration brute sans compression, ou OPUS pour un équilibre qualité/taille. Le WAV est idéal pour les sons courts et immédiats.

Variez les voix et la vitesse (0.25 à 4.0) pour éviter la monotonie des NPCs sans surcharger votre budget de caractères.

  • MP3 : léger, universel. FLAC/WAV : haute qualité.
  • OPUS : excellent rapport qualité/taille.
  • PCM : audio brut non compressé pour traitement immédiat.

Écoutez les 8 voix

Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. Nos huit voix pré-enregistrées couvrent une large palette d'archétypes, du narrateur clair à la voix documentaire profonde.

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

Plus sur ce site