Questions fréquentes
Quelle est l'URL exacte de l'API ?
L'endpoint principal est POST https://api.air186.info/v1/audio/speech. Vous envoyez le texte en JSON et recevez le fichier audio. Les autres points de terminaison incluent GET /v1/voices et GET /v1/models pour consulter les voix, formats et prix disponibles.
Dois-je utiliser le SDK OpenAI ou une requête HTTP ?
Vous pouvez utiliser le SDK OpenAI en modifiant la base URL vers https://api.air186.info/v1, ou effectuer une requête HTTP brute. La forme du corps de la requête est identique à celle de l'endpoint de parole d'OpenAI, garantissant une compatibilité directe.
Comment spécifier une voix masculine ou féminine ?
Indiquez le nom de la voix dans le champ voice du corps JSON. Les options féminines sont aria, nova, luna et sage. Les masculines sont felix, milo, atlas et orion. Chaque voix possède un registre vocal distinct pour adapter le ton à votre contenu touristique.
Que se passe-t-il si je dépasse la limite de caractères ?
La limite est de 4096 caractères par requête. Pour les textes plus longs, vous devez les diviser en plusieurs parties de cette taille, générer chaque segment audio séparément, puis assembler les fichiers résultants pour obtenir le fichier final complet et cohérent.
Les fichiers audio sont-ils binaires ou en base64 ?
L'API retourne le fichier audio directement dans la réponse. Les formats supportés sont mp3, wav, opus, flac et pcm. Le contenu est binaire, prêt à être enregistré sur votre serveur ou diffusé, sans nécessiter de décodage base64 supplémentaire.
Puis-je utiliser la même clé pour plusieurs projets ?
Oui, un compte dispose d'une seule clé active par site. Cette clé unique authentifie toutes vos requêtes, peu importe le nombre de projets ou d'applications qui l'utilisent simultanément. Vous pouvez en émettre une nouvelle à tout moment si nécessaire.
Comment tester l'API sans payer ?
Inscrivez-vous via Google pour recevoir 0,50 $ de crédit d'essai, valable sept jours. Cela permet de générer environ 50 000 caractères. Les comptes créés avec email et mot de passe ne bénéficient pas de ce crédit d'essai initial.
Y a-t-il une documentation pour les formats OPUS ?
Le format opus est un choix valide pour le champ response_format. Il suffit de le spécifier dans votre requête JSON. L'API génère alors le fichier audio dans ce codec, offrant un bon compromis entre qualité et taille de fichier.
La langue est-elle obligatoire dans la requête ?
Non, le champ language est optionnel. Si absent, la langue est déduite du script du texte. Pour le texte latin non anglais, il est recommandé de définir explicitement le code ISO pour garantir une prononciation correcte de la voix sélectionnée.
Combien de temps dure le traitement d'une requête ?
La génération prend environ une seconde par seconde de parole pour les textes longs. Les phrases courtes peuvent prendre quelques secondes. En cas de charge, les requêtes peuvent attendre dans une file d'attente avant d'être traitées séquentiellement.
Est-ce que l'API supporte les requêtes parallèles ?
Les requêtes sont traitées une par une. Sous forte charge, elles s'empilent dans une file d'attente. Cela signifie que vous ne bénéficiez pas de traitement véritablement parallèle simultané pour plusieurs requêtes envoyées rapidement, ce qui peut augmenter le temps total.
Comment révoquer ma clé API actuelle ?
Vous pouvez émettre une nouvelle clé à tout moment depuis votre tableau de bord. Dès la nouvelle clé créée, l'ancienne devient inactive immédiatement. Cela révoque efficacement l'accès de l'ancienne clé sans nécessiter de confirmation manuelle supplémentaire.
Les fichiers audio ont-ils une durée maximale ?
La limite est de 4096 caractères d'entrée par requête. Il n'y a pas de limite de durée fixe, mais la longueur du texte détermine la durée. Pour des audios longs, il faut fractionner le texte et assembler les fichiers audio.
Y a-t-il un endpoint pour lister les voix disponibles ?
Oui, la requête GET /v1/voices fournit la liste complète des voix, des langues et des formats supportés. Cet endpoint vous permet de consulter les voix, les formats et les tarifs disponibles.
Première requête
curl
curl https://api.air186.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.air186.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.air186.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 |
Obtention de votre clé API
Pour accéder à l'API VoixNumériques, rendez-vous sur la page /get-api-key/. L'inscription est possible via un compte Google ou par email avec mot de passe. Chaque compte est indépendant et lié à ce site spécifique.
Inscription via Google ou email
Choisissez votre méthode de connexion préférée. La création de compte est immédiate et ne nécessite pas de carte bancaire initiale.
Localisation de la clé dans le tableau de bord
Une fois connecté, votre tableau de bord affiche votre clé API (format tts-...). Cette clé sert à authentifier toutes vos requêtes via l'en-tête Authorization: Bearer.
- La clé est visible immédiatement après la connexion.
- Une seule clé active est valide par compte à un instant donné.
Réémission de clé en cas de perte
Si votre clé est compromise ou perdue, vous pouvez en générer une nouvelle depuis le tableau de bord. La clé précédente devient inactive instantanément.
Première requête cURL
Pour commencer, envoyez une requête POST à l'endpoint /v1/audio/speech. Le service attend un corps JSON contenant le texte à synthétiser, la voix choisie parmi les huit presets et le format audio souhaité. Cette méthode standardise l'intégration avec les outils existants.
La réponse contient le fichier audio binaire ou un code d'état indiquant le succès ou une erreur. Il est essentiel de vérifier les codes HTTP pour gérer les échecs, qui sont remboursés, et de traiter les données binaires pour les enregistrer localement.
Commande POST vers /v1/audio/speech
Utilisez curl pour envoyer votre texte. L'endpoint est https://api.air186.info/v1/audio/speech. Cette commande permet de tester rapidement la génération avant de l'intégrer dans vos workflows de production audio pour les audioguides.
- Endpoint : POST https://api.air186.info/v1/audio/speech
- Méthode : POST
- Contenu-Type : application/json
Exemple de corps JSON complet
Le corps de la requête doit inclure le modèle, l'entrée textuelle, la voix et le format. Voici un exemple concret pour générer une description de musée en français.
```json { "model": "tts-1", "input": "Bienvenue dans ce lieu historique.", "voice": "sage", "response_format": "mp3", "speed": 1.0 } ```
Gestion de l'authentification Bearer
Vous devez inclure votre clé API dans l'en-tête Authorization. Cette clé est générée lors de votre inscription sur /get-api-key/. Assurez-vous de ne pas la partager publiquement dans vos scripts.
Le format attendu est Authorization: Bearer tts-votre-clé-ici. Si la clé est invalide ou expirée, le serveur renverra une erreur 401.
- En-tête : Authorization: Bearer tts-...
Utilisation avec le SDK OpenAI
L'API fonctionne avec la même forme de requête que l'endpoint OpenAI Speech, ce qui permet d'utiliser les SDK officiels sans réécrire la logique de connexion. Il suffit d'adapter l'URL de base pour pointer vers notre infrastructure.
Cette compatibilité simplifie l'intégration dans vos systèmes de gestion de contenu existants pour les audioguides, en évitant le développement d'un client dédié.
Changement de la base URL
Pour utiliser notre API avec les SDK OpenAI, modifiez simplement la base_url vers https://api.air186.info/v1. Cette simple configuration permet au SDK d'envoyer les requêtes au bon endpoint POST /v1/audio/speech.
L'en-tête Authorization: Bearer doit contenir votre clé API unique, obtenue sur votre tableau de bord après inscription.
- Base URL : https://api.air186.info/v1
- Endpoint : POST /v1/audio/speech
Compatibilité avec les SDK officiels
Les bibliothèques Python et Node.js d'OpenAI sont entièrement compatibles car elles respectent le format JSON standard de l'API. Vous pouvez ainsi réutiliser votre code de génération audio existant avec simplement un changement de point d'entrée.
Aucun client spécifique à notre marque n'est nécessaire, ce qui réduit la dette technique et les dépendances externes pour vos projets de contenu touristique.
Exemple de code Python ou Node.js
Voici un exemple minimal en Python pour générer un fichier audio :
```python import os from openai import OpenAI client = OpenAI( base_url="https://api.air186.info/v1", api_key=os.getenv("API_KEY") ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Bienvenue dans notre musée.", response_format="mp3" ) with open("audio.mp3", "wb") as f: f.write(response.content) ```
La même logique s'applique en Node.js en instanciant le client OpenAI avec l'URL de base personnalisée. Le corps de la requête reste identique aux spécifications standards.
Paramètres de la requête
La génération audio repose sur deux modèles partageant le même moteur et le même tarif : tts-1 et tts-1-hd. Le choix ne concerne que la qualité perçue, sans différence de coût ni de capacité technique.
Vous disposez de huit voix préenregistrées, issues de lectures publiques (LibriTTS-R et LibriVox). Quatre voix féminines (Aria, Nova, Luna, Sage) et quatre masculines (Felix, Milo, Atlas, Orion) couvrent tous les styles, du narratif au dynamique.
Le format de sortie s'adapte à votre infrastructure de diffusion audioguide. Le MP3 assure une compatibilité web universelle, tandis que le WAV offre une qualité standard pour les systèmes de lecture professionnels.
Modèles tts-1 et tts-1-hd
L'API propose deux modèles identiques dans leur traitement : tts-1 et tts-1-hd. Ils utilisent le même moteur de synthèse et facturent le même prix de 10 $ par million de caractères. Cette équivalence permet de changer de modèle sans modifier votre logique d'intégration.
Lequel choisir dépend uniquement de vos critères auditifs pour les audioguides. La structure de la requête JSON reste strictement identique pour les deux options.
- Modèle par défaut : tts-1
- Haute fidélité : tts-1-hd
- Tarif identique : 10 $ / 1M caractères
Sélection des 8 voix disponibles
Huit voix sont disponibles, classées par timbre et registres. Elles sont issues d'enregistrements licenciés (LibriTTS-R, CC BY 4.0) et de lectures du domaine public (LibriVox). Chaque fichier généré contient un filigrane inaudible marquant son origine synthétique.
Pour les audioguides, la voix Atlas (neutre, style journal) convient aux informations factuelles, tandis que Luna (douce, conteuse) s'adapte aux récits historiques. Les voix comme Felix (énergique) ou Milos (convivial) conviennent aux annonces dynamiques.
- Féminines : Aria, Nova, Luna, Sage
- Masculines : Felix, Milo, Atlas, Orion
- Source : enregistrements licenciés et domaine public
Format de réponse audio (mp3, wav...)
Le champ response_format détermine le conteneur audio retourné. Le MP3 est recommandé pour la diffusion web et les applications mobiles grâce à sa large compatibilité. Le WAV garantit une qualité audio standard sans compression avec pertes, idéal pour les systèmes de lecture audioguide filaires.
D'autres formats sont disponibles selon vos besoins de stockage ou de post-traitement. Le choix du format n'influence pas la durée de génération ni le coût de la requête.
- mp3 : compatibilité web maximale
- wav : qualité audio standard
- opus : compression efficace
- flac : compression sans perte
- pcm : données brutes non encodées
Gestion de la vitesse et de la langue
Le champ speed ajuste le débit de parole entre 0,25 et 4,0 fois la vitesse normale. Cette fonctionnalité permet d'adapter la voix off aux contraintes d'audioguides en extérieur ou aux environnements calmes des musées, sans altérer le timbre de la voix sélectionnée.
Vitesse de 0.25 à 4.0
Une valeur de 1,0 correspond à la vitesse standard. Réduire la vitesse à 0,5 peut améliorer la compréhension des annonces complexes, tandis qu'une vitesse de 2,0 permet de couvrir plus de contenu dans un temps limité.
Spécification de la langue ISO
Vous pouvez forcer la langue cible en utilisant le code ISO (par exemple, fr pour le français, en pour l'anglais). Cette précision est recommandée pour les textes contenant des noms propres ou des ambiguïtés de prononciation.
Détection automatique du script
Si le paramètre language n'est pas défini, l'API détecte la langue basée sur le script du texte. Le texte en alphabet latin est par défaut considéré comme anglais. Pour une précision maximale avec du texte en français ou en allemand, spécifiez explicitement la langue.

Limites de taux et erreurs
La limite standard de 60 requêtes par minute suffit largement pour la plupart des besoins de production d'audioguides. Cependant, une limite initiale plus restrictive de 10 requêtes par minute s'applique jusqu'à votre premier rechargement de crédit. Cette contrainte temporaire permet de vérifier la validité de votre clé sans surcharger le service lors de vos premiers tests.
60 requêtes par minute par clé
Une fois votre compte approvisionné, vous pouvez envoyer jusqu'à soixante requêtes par minute. Ce débit est suffisant pour générer des dizaines de minutes de contenu audio par heure, ce qui convient parfaitement aux mises à jour fréquentes de contenus muséaux.
Limite initiale de 10 requêtes
Avant tout dépôt de fonds, votre clé est limitée à dix requêtes par minute. Cette restriction protège l'infrastructure lors de l'utilisation du crédit d'essai gratuit. Dès la première transaction USDT (TRC-20) confirmée, la limite passe automatiquement à soixante requêtes par minute.
Codes d'erreur standards HTTP
L'API retourne des codes HTTP standards pour indiquer l'état de la synthèse. Une erreur 429 signale que vous avez dépassé la limite de requêtes. Les erreurs 4xx indiquent généralement un problème avec la clé API ou les paramètres envoyés. Vérifiez toujours les logs de votre serveur pour diagnostiquer les échecs de génération.
- 401 : Clé API invalide ou manquante.
- 429 : Limite de requêtes dépassée (Retry-After inclus).
- 500 : Erreur interne du service de synthèse.
Traitement des longs textes
Pour les audioguides, la limite de 4096 caractères par requête nécessite une gestion précise des textes. Cette contrainte s'applique à chaque appel API individuel, incluant les espaces et la ponctuation.
Limite de 4096 caractères
Chaque génération audio est limitée à 4096 caractères. Si votre description de musée dépasse ce seuil, une seule requête ne suffira pas.
Découpage automatique du texte
Vous devez diviser manuellement ou via code votre contenu en segments de 4096 caractères maximum. Il n'y a pas de découpage automatique natif par l'API ; votre application doit gérer la logique de segmentation avant l'envoi des requêtes.
Assemblage des fichiers audio
L'API retourne chaque segment audio séparément. Votre système doit ensuite assembler ces fichiers audio pour créer l'audioguide final. La latence s'accumule, mais le traitement reste séquentiel et fiable.
Formats audio supportés
Le choix du format audio dépend de votre flux de travail de production audioguide. Vous pouvez sélectionner le format via le paramètre response_format lors de l'appel à l'API.
MP3 pour la compatibilité web
Le format MP3 est idéal pour la diffusion sur les applications mobiles et les sites web des musées. Il offre un bon équilibre entre qualité sonore et taille de fichier.
WAV pour la qualité audio standard
Le format WAV est recommandé pour les archivages ou les lectures hors ligne nécessitant une qualité non compressée. Il est pris en charge par la plupart des lecteurs audio des audioguides.
OPUS et FLAC pour la compression
OPUS offre une compression efficace pour les débits limités, tandis que FLAC assure une compression sans perte. Ces formats sont utiles pour économiser de l'espace de stockage sur les appareils.
Écoutez les 8 voix
Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. Toutes les voix peuvent prononcer n'importe quelle langue de cette liste, garantissant une cohérence acoustique sur votre site.
23 langues
Chaque voix peut parler n'importe laquelle de ces langues.
