Documentation API pour générer des voix off

Par Équipe éditoriale de VoixNumériques · Mis à jour 2026-11-19

Cette documentation explique comment intégrer notre API de synthèse vocale dans vos workflows de création d'audioguides et de contenus touristiques. Vous y trouverez les spécifications techniques pour transformer vos textes en fichiers audio via la méthode POST standard, compatible avec les outils courants du secteur.

Le guide couvre l'obtention de votre clé API, les paramètres de génération (voix, format, vitesse) et la gestion des longs textes. Il s'adresse spécifiquement aux agences et musées souhaitant automatiser la production de voix off réalistes sans investissement matériel lourd, en s'appuyant sur des exemples concrets et une documentation précise.

Documentation API pour générer des voix off

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.mp3

Python (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
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

Obtention de votre clé API

Illustration d'onde sonore pour: 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

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

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

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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.

Gestion de la vitesse et de la langue

Limites de taux et erreurs

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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

Illustration d'onde sonore pour: 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.

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. openai-node on GitHub
  3. FFmpeg documentation
  4. ISO 639 language codes
  5. Tether (USDT)
  6. IETF RFC 7845: Ogg Opus
  7. MDN: Web Speech API
  8. openai-python on GitHub
  9. Creative Commons Attribution 4.0
  10. LibriVox public-domain audiobooks
  11. Python documentation
  12. curl documentation

Plus sur ce site