Questions fréquentes
Quelle est la différence entre tts-1 et tts-1-hd ?
Les modèles tts-1 et tts-1-hd utilisent exactement le même moteur de synthèse et le même prix. Vous pouvez choisir l’un ou l’autre sans impact sur le coût, mais les rendus audio peuvent différer. La seule différence réside dans le nom du modèle envoyé dans la requête JSON, permettant une compatibilité directe avec les SDK existants.
Comment changer la langue de la voix ?
Ajoutez le champ language avec un code ISO à 2 lettres dans votre corps de requête. Si ce champ est omis, la langue est déduite du script (latin par défaut en anglais). Pour les textes latins non anglais, définissez explicitement le champ pour garantir la prononciation correcte, comme pour le français ou l’espagnol.
Puis-je utiliser le SDK OpenAI standard ?
Oui, la structure de la requête est identique à celle de l’endpoint OpenAI Speech. Il suffit de modifier l’URL de base (base_url) vers https://api.playah77.com/v1 et d’utiliser votre clé API VoixCélèbre. Les SDK officiels OpenAI fonctionnent ainsi sans adaptation majeure de votre côté.
Que signifie la limite de 4096 caractères ?
Chaque requête API accepte un maximum de 4096 caractères dans le champ input. Pour les textes plus longs, vous devez diviser manuellement le texte en segments respectant cette limite et joindre les fichiers audio résultants. Les espaces et ponctuation comptent dans ce décompte total.
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 avant le traitement. La vitesse de génération est d'environ 25 caractères par seconde pour les textes longs. Pour les phrases courtes, l’attente peut ajouter quelques secondes supplémentaires au temps de génération.
Les formats opus et flac sont-ils supportés ?
Oui, vous pouvez spécifier opus ou flac dans le champ response_format de votre requête. Les autres formats supportés sont mp3, wav et pcm. Le format choisi détermine uniquement le codec du fichier audio retourné dans la réponse, sans impact sur le prix ou la voix.
Quelle est la structure de la clé API ?
La clé commence par le préfixe tts-. Elle s’utilise dans l’en-tête Authorization: Bearer tts-.... Chaque compte possède une clé active ; en émettre une nouvelle invalide immédiatement l’ancienne. Vous pouvez révoquer et régénérer votre clé à tout moment depuis votre tableau de bord.
Est-ce que l'API retourne du streaming audio ?
Non, l’API ne supporte pas le streaming audio, WebSocket ou le retour partiel en temps réel. Vous envoyez le texte et recevez le fichier audio complet une fois la synthèse terminée. Le fichier est retourné directement dans la réponse HTTP, prêt à être sauvegardé ou diffusé.
Première requête
curl
curl https://api.playah77.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.playah77.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.playah77.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 commencer à utiliser l'API VoixCélèbre, rendez-vous sur la page d'inscription et créez un compte via Google ou un email. Cette étape fondamentale vous donne accès à votre tableau de bord dédié, où vous pourrez visualiser votre clé API, votre solde, vos caractères restants et votre historique d'utilisation.
Inscription sur la page d'accueil
L'inscription est rapide et sans engagement. Une fois connecté, vous accédez immédiatement à votre espace client où chaque clé est unique et liée à votre session active sur ce site spécifique.
Génération d'une clé Bearer
Votre clé API, format tts-..., est affichée directement dans votre tableau de bord. Elle sert de jeton d'authentification pour toutes vos requêtes. Vous pouvez la copier et l'utiliser immédiatement dans vos scripts ou intégrations no-code.
- Une seule clé active par compte à la fois
- Format standard Bearer Token pour l'en-tête Authorization
Révocation et nouvelle clé
Vous pouvez générer une nouvelle clé à tout moment depuis les paramètres de votre compte. Dès que la nouvelle clé est créée, l'ancienne devient invalide instantanément, assurant une sécurité maximale pour vos streams et vidéos sans interruption de service si vous mettez à jour votre configuration rapidement.
Première requête avec cURL
Commencez par tester l’API directement via votre terminal. La méthode la plus simple est d’utiliser cURL pour envoyer une requête POST à l’endpoint de synthèse vocale. Cette approche vous permet de vérifier rapidement que votre clé API fonctionne et que le format de sortie correspond à vos besoins avant d’intégrer la logique dans vos scripts de stream.
La commande cURL nécessite trois éléments essentiels : l’URL de l’endpoint, l’en-tête d’authentification Bearer et le corps JSON contenant le texte à synthétiser. Le serveur traite la demande et renvoie le fichier audio généré, prêt à être joué ou enregistré dans vos clips VTuber.
Exemple de commande cURL
Exécutez cette commande en remplaçant YOUR_API_KEY par votre clé et votre-texte par le texte à convertir. Le fichier output.mp3 sera créé dans votre répertoire courant.
curl -X POST https://api.playah77.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "voice": "aria", "input": "Bonjour et bienvenue sur le stream !", "response_format": "mp3"}' \ -o output.mp3
- Utilisez
tts-1outts-1-hd; les deux modèles utilisent le même moteur et le même prix. - La voix
ariaconvient parfaitement aux narrations claires et chaleureuses. - Le format
mp3est léger et universellement compatible avec les logiciels de montage.
Corps JSON de la requête
Le corps de la requête doit être un objet JSON valide. Le champ input accepte jusqu’à 4096 caractères, espaces et ponctuation inclus. Si vous ne spécifiez pas de language, le système devine la langue (anglais par défaut pour le script latin).
Vous pouvez ajuster la speed entre 0.25 et 4.0 pour adapter le débit de la parole à l’ambiance de votre stream. Le modèle model détermine la qualité audio mais pas le prix, qui reste identique pour tts-1 et tts-1-hd.
model: "tts-1" ou "tts-1-hd"input: texte brut (< 4096 chars)voice: l’une des 8 voix disponiblesresponse_format: mp3, wav, opus, flac, pcmspeed: 0.25 à 4.0language: code ISO optionnel
Réponse audio binaire
En cas de succès, le serveur retourne le fichier audio directement dans le corps de la réponse HTTP avec le code 200. Aucun JSON n’est retourné, seulement les octets du fichier audio. Pour les flux, ces données peuvent être redirigées vers un fichier ou un lecteur.
Si la synthèse échoue, une erreur JSON est renvoyée avec un code d’état approprié (4xx ou 5xx) et aucun frais ne vous sera imputé. Le fichier généré porte un filigrane inaudible indiquant qu’il s’agit d’une voix synthétique.
Utilisation avec le SDK OpenAI
L'API s'aligne sur le format de l'endpoint OpenAI, ce qui permet d'utiliser les SDK officiels sans réécrire la logique. Il suffit de pointer le client vers notre base URL pour bénéficier de la même structure de requête et de réponse.
Changement de base_url
Modifiez simplement la variable base_url de votre SDK pour la faire pointer vers https://api.playah77.com/v1. Cette seule configuration adapte les appels HTTP aux serveurs VoixCélèbre.
Compatibilité avec les SDK officiels
Les bibliothèques Python, Node.js et Go d'OpenAI fonctionnent nativement. Elles gèrent l'encodage JSON et les flux binaires sans ajustement majeur.
Configuration de l'authentification
Ajoutez votre clé API dans l'en-tête Authorization: Bearer <votre-clé>. Le SDK transmettra automatiquement cet identifiant avec chaque requête POST.
Champs de la requête API
La requête POST vers /v1/audio/speech nécessite un corps JSON précis. Chaque champ détermine le rendu final de votre narration VTuber ou de votre clip vidéo. La simplicité du format permet une intégration rapide sans dépendances complexes.
Assurez-vous que le texte ne dépasse pas 4096 caractères. Pour les scripts plus longs, divisez-les manuellement et joignez les fichiers audio générés séquentiellement pour une lecture fluide.
Modèle tts-1 vs tts-1-hd
Choisissez entre tts-1 et tts-1-hd. Les deux utilisent le même moteur de synthèse et le même tarif de 0,01 $ par 1 000 caractères. Le modèle HD offre un rendu audio différent, idéal pour les vidéos où le son est central.
- Même prix et même moteur pour les deux modèles.
- Compatibilité totale avec les champs standard.
Choix de la voix et de la langue
Sélectionnez une voix parmi 8 presets (ex. aria pour une narration claire, atlas pour un ton neutre). La langue est détectée automatiquement depuis le script, mais il est recommandé de spécifier le code ISO (ex. fr) pour éviter les erreurs avec le texte latin non anglais.
Vérifiez les 23 langues supportées : l'espagnol, le japonais, le français, l'allemand, etc. sont tous compatibles avec n'importe quelle voix.
- 8 voix : aria, nova, luna, sage, felix, milo, atlas, orion.
- Langue optionnelle mais recommandée pour les textes latins non anglais.
Format de sortie audio
Spécifiez le format via response_format. Les options incluent mp3, wav, opus, flac et pcm. Le MP3 est standard pour le web, tandis que le WAV ou le FLAC conviennent mieux aux montages vidéo nécessitant une qualité sans perte.
Le fichier audio binaire est retourné directement dans la réponse HTTP.
- Formats supportés : mp3, wav, opus, flac, pcm.
- Pas de streaming ni de WebSocket pour le chargement progressif.
Limites et contraintes techniques
Pour optimiser vos flux audio, il faut respecter les contraintes techniques de l'API. Chaque appel ne peut contenir que 4096 caractères, ce qui impose une segmentation logique pour les textes longs. Le débit est limité à 60 requêtes par minute par clé (10 requêtes par minute avant le premier rechargement).
Limite de 4096 caractères par requête
Chaque demande JSON accepte un maximum de 4096 caractères, espaces et ponctuation inclus. Pour générer une narration plus longue, vous devez diviser le texte en plusieurs requêtes successives et assembler les fichiers audio résultants.
- Seuls 4096 caractères sont autorisés par appel POST.
- Les caractères spéciaux et les espaces comptent dans la limite.
- Une logique de découpe côté client est nécessaire pour les textes longs.
Débit de 60 requêtes par minute
Votre clé API supporte jusqu'à 60 requêtes par minute. Cette limite s'applique par clé active. Pour les nouveaux comptes sans rechargement, le débit est réduit à 10 requêtes par minute.
- 60 requêtes/minute pour les comptes rechargés.
- 10 requêtes/minute pour les comptes sans top-up initial.
- Une nouvelle clé révoque l'ancienne instantanément.
File d'attente sous charge
Les requêtes sont traitées séquentiellement. En cas de charge élevée, votre demande peut attendre dans une file d'attente avant le début de la synthèse. Cela peut augmenter le temps de réponse global pour les gros volumes.
- Traitement séquentiel des demandes.
- Latence possible en période de forte activité.
- Temps de génération réel : ~25 caractères/seconde pour les textes longs.

Gestion des erreurs courantes
Une erreur courante est l’utilisation d’une clé API invalide ou expirée. Si votre clé a été révoquée pour en générer une nouvelle, l’ancienne cesse immédiatement de fonctionner. Vérifiez toujours que le jeton commence par tts- et qu’il correspond à votre compte actif sur playah77.com.
Clé API invalide ou expirée
Si la réponse indique une authentification échouée, régénérez votre clé depuis le tableau de bord. Une seule clé est active par compte ; la nouvelle prend le relais instantanément.
- Vérifiez le préfixe
tts-dans l’en-tête Authorization. - Assurez-vous qu’aucune autre session n’a révoqué la clé.
Texte trop long ou format incorrect
Chaque requête est limitée à 4096 caractères. Si votre script de VTuber dépasse cette limite, découpez le texte en segments plus courts et joignez les fichiers audio résultants. Les espaces et ponctuations comptent comme caractères.
- Utilisez le champ
inputpour le texte brut. - Respectez strictement la limite de 4096 caractères par appel.
Erreurs de limite de taux
Votre clé est limitée à 60 requêtes par minute. Si vous générez rapidement plusieurs clips pour un stream, un délai peut survenir après la première minute. En dessous de ce seuil, vous êtes limité à 10 requêtes par minute jusqu’à votre premier rechargement.
- Surveillez le code d’erreur 429 (Too Many Requests).
- Rechargez votre compte via un dépôt USDT (TRC-20) pour bénéficier du débit de 60 req/min.
Endpoints disponibles
L'API expose trois points d'entrée principaux pour interagir avec le moteur de synthèse. Vous pouvez générer de l'audio, lister les voix disponibles ou vérifier les modèles actifs.
Ces endpoints suivent une structure RESTful simple, compatible avec les outils no-code et les scripts Python courants dans l'écosystème streaming.
POST /v1/audio/speech
C'est le point d'entrée principal. Envoyez du texte brut en JSON pour recevoir un fichier audio généré à la volée.
Supporte les paramètres de voix, de vitesse et de format. La limite est de 4096 caractères par appel.
- Body JSON: input, voice, model, response_format
- Auth: Bearer <your_key>
- Format: mp3, wav, opus, flac, pcm
GET /v1/voices
Liste les 8 voix disponibles avec leurs métadonnées (langues supportées, formats).
Permet de découvrir les presets comme Aria, Nova ou Atlas avant de faire vos premiers appels.
GET /v1/models
Retourne la liste des modèles actifs, notamment tts-1 et tts-1-hd.
Utile pour vérifier la disponibilité des modèles avant l'intégration dans votre pipeline.
Exemples de code pour streamers
L'API TTS s'intègre facilement dans les workflows de streamers no-code. Générez des voix off pour vos streams, vidéos et clips sans effort technique. Transformez du texte brut en audio immersif pour enrichir vos VTubings et vos montages.
Utilisez des scripts Python simples ou des plugins OBS pour automatiser la narration. Chaque requête respecte les limites de 4096 caractères et le débit de 60 requêtes par minute.
Script Python basique
Importez le SDK OpenAI et modifiez base_url vers https://api.playah77.com/v1. Utilisez votre clé Bearer pour envoyer le texte via client.audio.speech.create(). Le fichier audio est retourné directement pour lecture ou enregistrement.
- Initialisation du client avec la clé API
- Appel à
audio.speech.createavec le modèletts-1 - Sauvegarde du fichier MP3 ou WAV reçu
Intégration dans OBS ou Streamlabs
Configurez une source 'Source de sortie audio' pour lire les fichiers générés. Utilisez un script externe pour pré-générer les narrations avant le stream. Cela évite la latence de l'API en direct.
- Lien vers le fichier audio local
- Activation de la source dans OBS
- Test de la clarté audio
Génération automatique de clips
Scindez les longs textes en segments de 4096 caractères. Joignez les fichiers audio générés pour créer des clips narratifs fluides. Idéal pour les résumés de streams ou les vidéos YouTube.
- Découpe du texte en chunks
- Enchaînement des fichiers audio
- Export final en MP3
Écoutez les 8 voix
Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. Sa voix dynamique soutient le rythme effréné des streams Twitch.
23 langues
Chaque voix peut parler n'importe laquelle de ces langues.
