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.mp3Python (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 | |
|---|---|
aria | femme |
nova | femme |
luna | femme |
sage | femme |
felix | homme |
milo | homme |
atlas | homme |
orion | homme |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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é
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
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
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
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
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
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é.

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
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
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.
23 langues
Chaque voix peut parler n'importe laquelle de ces langues.
