Questions fréquentes
Quelle est la structure JSON de la requête ?
La requête POST vers /v1/audio/speech contient les champs model, input, voice, response_format, speed et language. Le champ input accepte le texte à synthétiser. L'en-tête Authorization: Bearer doit inclure votre clé API unique. Cette structure JSON est compatible avec les standards API courants pour une intégration directe.
Comment changer la base URL pour le SDK OpenAI ?
Modifiez simplement la propriété base_url du client SDK OpenAI pour pointer vers https://api.victini.info/v1. Utilisez ensuite la méthode standard speech avec votre clé API VoixParlante. Cette approche permet de réutiliser le code existant sans dépendre d'un SDK propriétaire spécifique à notre plateforme.
Les voix sont-elles spécifiques à une langue ?
Non, chaque voix peut prononcer n'importe laquelle des 23 langues supportées. Par exemple, la voix Aria peut parler français ou japonais. Si la langue n'est pas précisée, l'API devine la langue basée sur le script, par défaut anglais pour le texte latin.
Puis-je ajuster la vitesse de parole ?
Oui, le paramètre speed accepte une valeur numérique entre 0.25 et 4.0. La valeur par défaut est 1.0. Cela permet d'adapter le débit de parole à vos besoins de montage audio sans nécessiter de traitement post-production supplémentaire pour modifier la vitesse du fichier généré.
Quelles sont les langues supportées par l'API ?
L'API supporte 23 langues : 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 et turc. Les langues comme le vietnamien ou le thaï ne sont pas disponibles.
Comment gérer les requêtes échouées ?
Les requêtes échouées sont gratuites. Si la synthèse échoue, le montant est remboursé intégralement sur votre solde. Vous n'êtes pas facturé pour les tentatives infructueuses, ce qui garantit que vous ne payez que pour les fichiers audio générés avec succès et livrés dans la réponse.
Y a-t-il une limite de taille pour le texte ?
Oui, chaque requête est limitée à 4096 caractères. Pour les textes plus longs, vous devez diviser le contenu en plusieurs parties de cette taille maximale et assembler les fichiers audio résultants. Les espaces et la ponctuation comptent dans ce décompte de caractères.
Le format PCM est-il adapté aux podcasts ?
Le format PCM est disponible mais non compressé, ce qui génère des fichiers volumineux. Pour les podcasts, le format MP3 ou Opus est généralement préférable pour son rapport qualité-taille optimal. Le WAV et le FLAC sont aussi disponibles selon vos besoins de qualité audio spécifique.
Comment révoquer ma clé API ?
Générez une nouvelle clé API depuis votre tableau de bord. Dès l'émission de la nouvelle clé, l'ancienne devient inactive immédiatement. Vous n'avez pas besoin de contacter le support pour révoquer manuellement l'ancienne clé, le processus est automatisé et instantané pour une sécurité optimale.
Les requêtes sont-elles traitées en parallèle ?
Non, les requêtes sont traitées séquentiellement. Sous charge, une requête peut attendre dans une file d'attente. Cela signifie que le temps de génération s'additionne si vous envoyez plusieurs demandes simultanément,
Quelle est la vitesse de génération typique ?
La vitesse est d'environ 25 caractères par seconde pour les textes longs, soit un temps de génération proche du temps réel. Pour les phrases courtes, la génération prend quelques secondes supplémentaires en raison du traitement initial. Les délais peuvent augmenter si la file d'attente est chargée.
Dois-je installer une dépendance spécifique ?
Aucune dépendance propriétaire n'est requise. Vous pouvez utiliser n'importe quel client HTTP standard ou le SDK OpenAI en modifiant l'URL de base. Cela offre une grande flexibilité technique, permettant une intégration simple dans divers environnements de développement sans gérer de SDK propriétaire.
Comment vérifier les voix disponibles via API ?
Effectuez une requête GET sur l'endpoint /v1/voices. Cette réponse liste les 8 voix disponibles, les langues supportées et les formats audio disponibles. Vous pouvez également consulter l'endpoint /v1/models pour obtenir des informations détaillées sur les modèles de synthèse vocale actuellement opérationnels.
Y a-t-il des erreurs courantes avec les accents ?
L'API ne gère pas le SSML ni les dictionnaires de prononciation personnalisés. Si le texte contient des mots étrangers ou des noms propres, la prononciation peut être standardisée selon la langue détectée. Il est recommandé de définir explicitement le paramètre language pour éviter les détections automatiques erronées.
Première requête
curl
curl https://api.victini.info/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.victini.info/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.victini.info/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 |
Configuration de la clé API
Pour utiliser l'API VoixParlante, une clé unique est indispensable. L'authentification s'effectue via l'en-tête Authorization: Bearer tts-... inclus dans chaque requête. Cette clé garantit l'accès à votre solde et le suivi de la consommation.
Génération de clé
Accédez à la page /get-api-key/ et connectez-vous avec Google ou un email. La clé API s'affiche immédiatement. Chaque compte ne possède qu'une seule clé active à la fois.
Authentification Bearer
Incluez toujours Authorization: Bearer tts-... dans vos en-têtes HTTP. Sans ce token, les requêtes sont refusées. La clé est spécifique à ce site victini.info.
- Format :
Authorization: Bearer tts-votre_clé - Une seule clé active par compte
Révoquer une clé
Générez une nouvelle clé depuis le tableau de bord. L'ancienne est invalidée instantanément, même si elle est encore utilisée dans certains scripts. Révoquez dès qu'une clé est compromise.
Première requête cURL
Voici la méthode standard pour générer un fichier audio. L'endpoint principal accepte une requête POST au format JSON. Cette approche garantit une compatibilité immédiate avec les environnements de développement courants sans dépendance à un SDK propriétaire.
Le corps de la requête définit le modèle, la voix, le texte à synthétiser et le format de sortie. Les paramètres sont stricts : le texte ne doit pas dépasser 4 096 caractères et la clé doit être authentifiée via l'en-tête Bearer.
Exemple POST /v1/audio/speech
Utilisez cURL pour envoyer votre requête. L'URL cible est https://api.victini.info/v1/audio/speech. Remplacez VOTRE_CLE_API par votre clé unique.
La commande suivante illustre la structure minimale requise pour une première génération réussie.
- Méthode : POST
- URL : https://api.victini.info/v1/audio/speech
- En-tête : Authorization: Bearer VOTRE_CLE_API
- Contenu-Type : application/json
Corps JSON
Le payload JSON doit inclure le modèle (tts-1 ou tts-1-hd), la voix sélectionnée et le texte. Le format audio par défaut est mp3. Les autres formats sont disponibles selon vos besoins de stockage ou de qualité.
Exemple de corps de requête valide pour une synthèse basique en français.
- "model": "tts-1"
- "voice": "nova"
- "input": "Bonjour, voici un test de l'API.", "response_format": "mp3"
Réponse audio
En cas de succès, le serveur retourne le fichier audio binaire directement dans le corps de la réponse HTTP. Aucun métadonnées JSON supplémentaires ne sont renvoyés pour la charge utile audio.
Si la synthèse échoue, un code d'état approprié (comme 400 ou 500) est retourné avec un message d'erreur explicite. Le fichier généré ne contient pas de métadonnées audibles spécifiques.
Utilisation avec le SDK OpenAI
L'API VoixParlante suit le même format de requête que l'API OpenAI, ce qui permet d'utiliser les SDK officiels sans réécriture complexe. Il suffit d'ajuster l'URL de base pour pointer vers nos serveurs.
Cette compatibilité simplifie l'intégration pour les développeurs familiarisés avec l'écosystème OpenAI, garantissant une transition rapide vers notre infrastructure TTS.
Changement de base_url
Modifiez la variable base_url du SDK pour l'aligner sur https://api.victini.info/v1. Cette configuration redirige toutes les requêtes vers notre endpoint POST /v1/audio/speech tout en conservant la structure JSON standard.
L'en-tête Authorization doit contenir votre clé API VoixParlante (format tts-...).
- Exemple :
base_url="https://api.victini.info/v1"
Même format de requête
Les champs model, input, voice et response_format sont identiques à ceux d'OpenAI. Vous pouvez passer directement vos scripts Python ou Node.js existants après cette simple adaptation d'URL.
La limite de 4096 caractères par requête s'applique rigoureusement, comme indiqué dans les spécifications du modèle.
Compatibilité des clients
Les SDK OpenAI officiels (versions récentes) sont entièrement compatibles. Aucune adaptation spécifique ni middleware n'est requis pour les appels standards de synthèse vocale.
Cette approche garantit une maintenance simplifiée pour vos intégrations existantes sans dépendre d'une bibliothèque propriétaire.
Paramètres de voix et langue
La sélection de la voix influence directement la tonalité du contenu audio généré. L'API propose huit presets distincts, répartis entre voix féminines et masculines, permettant d'adapter le rendu à des contextes variés allant de la narration claire à des tons plus institutionnels ou documentaires.
Chaque voix est issue d'enregistreements licenciés et génère un audio marqué par un filigrane inaudible. Le choix du preset doit précéder l'appel à l'endpoint de synthèse pour garantir une cohérence stylistique dans vos productions podcasts.
Liste des 8 voix
Huit presets sont disponibles, chacun optimisé pour un usage spécifique. Les voix féminines incluent Aria (narratrice), Nova (dynamique), Luna (douce) et Sage (instructionnelle). Côté masculin, Felix offre un ton promotionnel, Milo est conversationnel, Atlas assure une neutralité informative et Orion convient aux documentaires profonds.
Ces presets sont statiques ; aucune personnalisation fine ou clonage de voix n'est proposé. Sélectionnez celui qui correspond le mieux à votre audience cible avant de soumettre le texte.
- Aria : narratrice, claire et chaleureuse.
- Nova : voix lumineuse et dynamique.
- Luna : ton doux pour le storytelling.
- Sage : calme, idéale pour l'instruction.
- Felix : énergique, adapté aux promos.
- Milo : conversationnel et amical.
- Atlas : neutre, style journal d'info.
- Orion : voix profonde, style documentaire.
Détection automatique
Si le paramètre language n'est pas fourni, le système tente d'identifier la langue via le script du texte. Pour le texte en latin, la langue par défaut est l'anglais. Cette méthode convient si le contenu est strictement monolingue ou si l'anglais est dominant.
Spécification ISO
Pour des textes en latin mais non anglais, ou pour forcer une prononciation précise, spécifiez le code ISO de la langue. Cette approche garantit que la voix génère le phonème correct, évitant les erreurs d'accentuation courantes en détection automatique.
Les 23 langues supportées incluent l'arabe, le chinois, le français, l'allemand, le japonais, l'espagnol, etc. Toute langue non listée (comme le vietnamien ou le thaï) ne sera pas traitée correctement même avec une détection.
- Code ISO 639-1 recommandé.
- Évite les confusions d'accentuation.
- Fonctionne avec toutes les voix.
Formats de sortie audio
Le format de sortie est spécifié via le champ response_format dans le corps de la requête JSON. Vous pouvez choisir entre MP3, WAV, OPUS, FLAC ou PCM selon vos besoins de compatibilité et de qualité.
MP3 et WAV
MP3 est le format standard recommandé pour sa compatibilité universelle et son rapport qualité/poids optimal. WAV offre une audio non compressée, idéale pour les workflows d'édition professionnelle nécessitant une intégrité absolue des données.
Opus et FLAC
OPUS assure une compression efficace avec une bonne qualité, adaptée aux archives légères. FLAC conserve une compression sans perte, idéal pour la préservation archivistique sans l'overhead des WAV.
PCM non compressé
PCM retourne le flux audio brut non compressé. Il est utile pour les intégrations systèmes nécessitant un traitement audio brut immédiat sans décodage préalable.

Limites de taux et files d'attente
Votre clé API est limitée à 60 requêtes par minute. Cette limite s'applique par clé et non par compte. Si vous émettez des requêtes plus rapidement que ce plafond, le serveur retourne une erreur HTTP 429.
En cas de charge élevée, les requêtes sont traitées séquentiellement. Cela peut entraîner des délais d'attente supplémentaires avant le début de la synthèse vocale. Cette file d'attente est interne et transparente pour l'utilisateur.
60 requêtes par minute
Le quota strict de 60 requêtes par minute s'applique à chaque clé API active. Si vous émettez plus de 60 demandes dans une fenêtre de 60 secondes, la septième requête suivante recevra une erreur 429 Too Many Requests. Cette limite est globale pour votre clé, quel que soit le nombre d'utilisateurs ou de serveurs d'application utilisant la même clé.
File d'attente en charge
Lorsque le serveur est sous forte charge, les requêtes sont traitées une par une. Cela signifie qu'une requête peut attendre dans une file d'attente avant d'être synthétisée. Ce délai varie selon le volume de traffic mais reste généralement inférieur à quelques secondes pour les textes courts.
Gestion des erreurs 429
Une erreur 429 indique que vous avez dépassé votre quota de 60 requêtes par minute. Vous devez attendre que la fenêtre de temps se réinitialise avant de réessayer. Nous recommandons d'implémenter une logique de réessai avec backoff exponentiel dans vos applications pour gérer ces pics de trafic
- Implémentez un mécanisme de file d'attente côté client.
- Surveillez vos comptes d'utilisation via le tableau de bord.
Gestion des textes longs
Le service impose une limite stricte de 4 096 caractères par requête API, espaces et ponctuation inclus. Pour les articles ou les livres audio dépassant ce seuil, le texte doit être segmenté en plusieurs appels successifs avant la génération audio.
Chaque segment généré produit un fichier audio indépendant. Pour obtenir un fichier final continu, il est nécessaire de concaténer ces clips dans l'ordre chronologique. Cette méthode garantit la compatibilité avec tous les formats supportés sans perte de synchronisation.
Découpage 4096 caractères
La limite s'applique au corps de la requête input. Tout texte supérieur doit être divisé manuellement ou automatiquement en blocs respectant cette contrainte. Le comptage inclut tous les caractères, y compris les espaces et la ponctuation.
- Limite stricte : 4 096 caractères par requête POST.
- Comptage inclusif : espaces et ponctuation comptent.
- Langue non contraignante pour la limite de longueur.
Concaténation audio
L'API retourne un fichier audio binaire par segment. Pour restituer un texte long, vous devez assembler ces fichiers dans le même ordre que le découpage initial. Aucun métadonnées de synchronisation n'est fourni par l'API pour cette opération.
Les fichiers résultants doivent être combinés sans insertions de silence supplémentaires, sauf si votre outil de traitement audio le nécessite pour lisser les transitions entre les segments générés séparément.
- Format de sortie identique au premier segment.
- Ordre chronologique strict pour la reconstruction.
- Aucune métadonnée de jointure fournie.
Exemple de script
Un script Python utilisant requests peut découper le texte en chunks de 4096 caractères, envoyer chaque requête, puis fusionner les fichiers WAV ou MP3 reçus. Cette approche standardise le traitement des longs contenus pour les podcasts ou les audiobooks.
- Utiliser une boucle pour itérer sur les chunks.
- Stockage temporaire des fichiers audio intermédiaires.
- Fusion finale via une bibliothèque audio tierce.
Codes d'erreur courants
L'API retourne des codes d'état HTTP standard pour indiquer le résultat de chaque requête de synthèse. Ces codes permettent d'intégrer une gestion robuste des erreurs dans vos workflows de production audio.
Erreur 401 Clé invalide
Ce code indique que la clé fournie dans l'en-tête Authorization est incorrecte ou expirée. Vérifiez que le format est Bearer tts-... et qu'il correspond à votre compte actif sur victini.info.
- Vérifiez la clé dans le tableau de bord
- Assurez-vous qu'aucune espace n'est incluse
- Générez une nouvelle clé si nécessaire
Erreur 429 Limite dépassée
L'erreur 429 signale que vous avez atteint la limite de 60 requêtes par minute. Les requêtes supplémentaires sont refusées jusqu'à ce que le quota se réinitialise, sauf si la file d'attente est active.
- Limite : 60 requêtes/minute
- File d'attente possible sous charge
- Augmentation à 10/min sans top-up
Erreur 500 Synthèse échouée
Une erreur 500 signifie que la synthèse a échoué côté serveur. Dans ce cas, le montant est intégralement remboursé sur votre solde. Vous pouvez réessayer la requête sans pénalité.
- Remboursement automatique
- Vérifiez le format JSON
- Contrôlez la longueur du texte
Écoutez les 8 voix
Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. Utilisez cette voix pour les résumés trimestriels ou les comptes-rendus techniques.
23 langues
Chaque voix peut parler n'importe laquelle de ces langues.
