Documentation technique pour l'intégration API

Par L'équipe éditoriale VoixRH · Mis à jour 2026-11-19

Cette documentation technique explique comment intégrer l’API VoixRH dans vos outils de e-learning pour générer rapidement de l’audio à partir de vos supports HR. Vous y trouverez les spécifications pour envoyer du texte et recevoir des fichiers audio via un endpoint compatible avec le SDK OpenAI, idéal pour automatiser la narration destinée à vos collaborateurs.

Découvrez ici les paramètres essentiels comme le choix des voix, des formats ou la gestion des langues, ainsi que les limites de quota et les codes d’erreur. Que vous utilisiez Python ou des appels cURL directs, ces exemples concrets vous guideront pour transformer vos textes en narrations claires, en respectant les contraintes techniques de l’API.

Documentation technique pour l'intégration API

Questions fréquentes

Quelle est la structure exacte du corps JSON ?

Le corps contient model ("tts-1" ou "tts-1-hd"), input (texte jusqu’à 4096 caractères), voice (l’une des 8 voix), response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0) et language (code ISO optionnel). L’authentification utilise Authorization: Bearer tts-.... Cet envoi se fait par POST sur /v1/audio/speech.

Comment spécifier une voix masculine ?

Choisissez parmi les quatre voix masculines : felix (énergique), milo (conversationnel), atlas (neutre) ou orion (profond). Elles sont disponibles via l’endpoint GET /v1/voices. Chaque voix peut parler n’importe lequel des 23 langues supportées sans ajustement supplémentaire.

La clé API expire-t-elle ?

Non, la clé API ne expire pas. Elle reste active jusqu’à ce que vous en émettiez une nouvelle. La génération d’une nouvelle clé invalide immédiatement l’ancienne. Vous pouvez en créer une à tout moment depuis votre tableau de bord.

Puis-je utiliser le SDK Node.js ?

Oui, le SDK OpenAI fonctionne parfaitement. Il suffit de modifier l’URL de base (base_url) vers https://api.g111.info/v1 et d’utiliser votre clé VoixRH. Le SDK officiel d’OpenAI est recommandé pour une intégration rapide et fiable avec notre endpoint.

Quelle est la taille maximale d'une requête ?

La taille maximale est de 4096 caractères par requête. Les espaces et la ponctuation comptent pour un caractère. Si votre texte dépasse cette limite, vous devez le découper en plusieurs parties pour respecter la contrainte de taille de chaque appel API.

Comment gérer les textes de plus de 4096 caractères ?

Découpez votre texte en segments de 4096 caractères maximum. Envoyez chaque segment via une requête distincte. Enfin, concaténez les fichiers audio reçus pour obtenir la narration complète. Cela garantit que chaque partie respecte la limite imposée par l’API.

Les fichiers audio sont-ils stockés après la réponse ?

Non, les fichiers audio générés ne sont pas stockés. Ils sont retournés directement dans la réponse de l’API. Seules les métadonnées de la requête (heure, caractères, statut) sont conservées à des fins de facturation et de suivi d’utilisation.

Comment réinitialiser ma clé API ?

Générez simplement une nouvelle clé depuis votre tableau de bord. La nouvelle clé devient active immédiatement. L’ancienne clé est invalidée à l’instant même où la nouvelle est créée. Vous pouvez effectuer cette opération autant de fois que nécessaire.

Quelle vitesse est recommandée pour la formation ?

La vitesse par défaut est souvent adaptée, mais vous pouvez ajuster le paramètre speed entre 0,25 et 4,0. Ajustez selon le rythme de parole souhaité pour vos collaborateurs.

Le format PCM est-il supporté ?

Oui, le format PCM est supporté via le champ response_format. Vous pouvez également choisir entre mp3, wav, opus et flac. Ce format brut est utile si vous avez besoin d’une audio non compressée pour vos outils de traitement audio internes.

Y a-t-il une limite de durée par fichier ?

La limite est basée sur le nombre de caractères (4096 max), pas sur la durée. La durée varie selon la vitesse et la voix. En moyenne, cela génère environ 25 caractères par seconde de parole. Les textes longs nécessitent plusieurs appels.

Comment savoir si une requête a échoué ?

L’API retourne un code d’erreur HTTP spécifique en cas d’échec. Si la synthèse échoue, aucun frais n’est appliqué. Vérifiez les codes de réponse pour détecter les erreurs et réessayez si nécessaire après correction des paramètres.

Le watermark est-il audible ?

Non, le filigrane numérique est inaudible. Il marque chaque fichier généré comme étant une parole synthétique.

Dois-je gérer les erreurs de réseau moi-même ?

Oui, vous devez gérer les erreurs de réseau et les timeouts. Les requêtes sont traitées séquentiellement, ce qui peut créer des files d’attente en cas de charge. Prévoyez des mécanismes de réessai pour assurer la fiabilité de vos intégrations API.

Première requête

curl

curl https://api.g111.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.g111.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.g111.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 la clé API

Illustration d'onde sonore pour: Obtention de la clé API

Pour utiliser l'API VoixRH, commencez par créer un compte sur la page /get-api-key/. Vous pouvez vous inscrire via Google (avec un essai gratuit de 0,50 $) ou par e-mail et mot de passe. Chaque site héberge des comptes indépendants.

Création de compte

Création de compte

La création est immédiate. L'essai de 7 jours offre 50 000 caractères, suffisants pour tester l'intégration avant de payer à l'usage.

Récupération de la clé

Récupération de la clé

Une fois connecté, votre tableau de bord affiche votre clé API unique (format tts-...). Copiez-la pour l'ajouter à l'en-tête Authorization: Bearer de vos requêtes.

Gestion des clés actives

Une seule clé active par compte est autorisée. Vous pouvez en émettre une nouvelle à tout moment ; l'ancienne devient invalide instantanément, ce qui simplifie la répartition des accès entre les développeurs.

Première requête cURL

Illustration d'onde sonore pour: Première requête cURL

Pour tester rapidement votre intégration, envoyez une requête POST à l'endpoint de synthèse. Le corps de la requête contient le texte à convertir et les paramètres audio de base.

Exemple de code JSON

```json { "model": "tts-1", "input": "Bienvenue dans votre formation RH", "voice": "sage", "response_format": "mp3" } ```

Paramètres de base

Spécifiez le modèle (tts-1 ou tts-1-hd), le texte (max 4096 caractères), la voix et le format. L'en-tête Authorization: Bearer <votre-clé> est obligatoire. Si le texte n'est pas dans un script latin par défaut, définissez le paramètre language.

Réponse audio

Le serveur retourne le fichier audio binaire. En cas d'échec de la synthèse, la requête est gratuite et un code d'erreur est renvoyé.

Exemple de code JSON

```bash curl -X POST https://api.g111.info/v1/audio/speech \\ -H "Authorization: Bearer tts-..." \\ -H "Content-Type: application/json" \\ -d '{ "model": "tts-1", "input": "Bienvenue dans votre formation RH", "voice": "sage", "response_format": "mp3" }' ```

Paramètres de base

Le champ input accepte jusqu'à 4096 caractères. Les espaces et ponctuation comptent. Pour des langues autres que l'anglais avec alphabet latin, définissez explicitement le paramètre language (ex: fr) pour éviter une détection incorrecte.

Réponse audio

En cas de succès, vous recevez le fichier audio au format demandé. En cas d'échec, aucun frais n'est appliqué et un code d'erreur HTTP est retourné pour vous aider au débogage.

Utilisation avec le SDK OpenAI

Illustration d'onde sonore pour: Utilisation avec le SDK OpenAI

L'API VoixRH adopte la même structure de requête que l'API Speech d'OpenAI. Cela permet aux équipes techniques d'utiliser directement les SDK officiels existants en modifiant simplement l'URL de base. Cette compatibilité évite de réécrire les clients de connexion pour générer des audio de e-learning.

Configuration du base_url

Pointez votre SDK vers https://api.g111.info/v1 au lieu de l'endpoint OpenAI. Utilisez votre clé API VoixRH (tts-...) dans l'en-tête Authorization. La structure JSON du corps de la requête reste identique, facilitant l'intégration rapide dans vos pipelines de formation existants.

Compatibilité des SDK

Les SDK officiels OpenAI (Python, Node.js, etc.) fonctionnent nativement. Aucune adaptation complexe n'est nécessaire pour les appels HTTP standard. Vous bénéficiez ainsi de la stabilité des bibliothèques éprouvées sans dépendre d'un SDK propriétaire supplémentaire.

  • SDK Python OpenAI
  • SDK Node.js OpenAI
  • Appels HTTP REST standards

Exemple en Python

Initialisez le client avec la nouvelle base URL et votre clé. Envoyez le texte et le modèle tts-1. Le SDK gère l'authentification et retourne le fichier audio binaire directement dans la réponse, prêt à être sauvegardé ou diffusé.

Choix des formats audio

Illustration d'onde sonore pour: Choix des formats audio

Le format audio choisi détermine l'équilibre entre la qualité sonore et le poids des fichiers pour votre plateforme e-learning. Chaque format sert un usage spécifique dans vos workflows de production de contenu pour les collaborateurs.

MP3 pour le web

Le MP3 est le format par défaut, optimisé pour une diffusion fluide sur tous les navigateurs et appareils mobiles. Il offre un bon compromis entre taille de fichier et lisibilité, idéal pour les modules de formation en ligne.

WAV pour la qualité

Le WAV fournit une qualité sonore adaptée à la narration, sans compression perte. Ce format brut est recommandé pour les archives internes ou les intégrations nécessitant une fidélité maximale au signal vocal généré.

FLAC et OPUS

Le FLAC conserve une qualité parfaite sans compression avec perte, utile pour l'archivage professionnel. L'OPUS, en revanche, offre un taux de compression très élevé tout en maintenant une excellente intelligibilité, parfait pour les connexions à bande passante limitée.

Gestion des voix et de la langue

Illustration d'onde sonore pour: Gestion des voix et de la langue

VoixRH propose huit voix distinctes, générées à partir d'enregistrements licenciés, pour varier les tons de vos modules e-learning. Vous pouvez choisir entre des voix féminines comme Aria (narratrice) ou Nova (dynamique), et masculines comme Felix (promo) ou Atlas (neutre).

La gestion linguistique est flexible : vous pouvez forcer une langue ou laisser le système la deviner. Chaque voix peut parler n'importe quel des 23 langues supportées.

Liste des 8 voix

Les voix sont calibrées pour des usages professionnels clairs. Aria offre un ton chaleureux et clair, tandis que Luna convient au storytelling. Sage est idéal pour l'instruction, et Milo pour une conversation conviviale. Orion a un ton profond, adapté au documentaire.

  • Aria : narratrice chaleureuse et claire
  • Nova : voix brillante et dynamique
  • Luna : douceur pour le storytelling
  • Sage : calme pour l'instruction
  • Felix : énergie pour les promos
  • Milo : conversationnel
  • Atlas : ton neutre type actualités
  • Orion : profondeur documentaire

Spécification de la langue

Vous pouvez indiquer le code ISO de la langue dans la requête pour garantir la prononciation exacte. C'est recommandé pour les textes en latin non anglais, car le défaut est l'anglais. Les 23 langues supportées incluent le français, l'espagnol, l'allemand et le japonais, entre autres.

Détection automatique

Si le champ language est omis, l'API devine la langue selon la police d'écriture. Le texte en caractères latins sera traité en anglais par défaut. Pour du texte latin en français ou en italien, définissez explicitement le paramètre language pour éviter les erreurs de prononciation.

Gestion des voix et de la langue

Limites et quotas

Illustration d'onde sonore pour: Limites et quotas

Votre clé API est soumise à une limite de 60 requêtes par minute. Avant votre premier rechargement, ce quota est réduit à 10 requêtes pour limiter la consommation du crédit d'essai.

Chaque appel ne peut contenir que 4096 caractères. Pour les textes plus longs, vous devez découper votre contenu et joindre les fichiers audio générés.

60 requêtes par minute

Le système autorise 60 requêtes par minute par clé active. Avant tout rechargement de solde, cette limite est de 10 requêtes par minute.

Limite de 4096 caractères

Chaque corps de requête est limité à 4096 caractères, espaces et ponctuation incluss. Pour les scripts de formation plus longs, divisez le texte en plusieurs appels et assemblez les fichiers audio résultants.

File d'attente sous charge

Les requêtes sont traitées séquentiellement. En période de forte charge, un délai d'attente peut survenir avant le début de la synthèse. Comptez environ 25 caractères générés par seconde pour les textes longs.

Codes d'erreur courants

Illustration d'onde sonore pour: Codes d'erreur courants

Lors de l'intégration de l'API VoixRH, les développeurs peuvent rencontrer trois codes d'erreur principaux. Comprendre leur origine permet de maintenir un flux de génération audio stable pour les formations e-learning. Chaque erreur correspond à un état spécifique de la requête ou du compte.

Une gestion rigoureuse des erreurs évite les interruptions dans la diffusion de contenu à vos collaborateurs. Voici comment identifier et résoudre les problèmes courants liés à l'authentification, aux quotas et à la synthèse elle-même.

Erreur 401 (clé invalide)

Ce code indique que votre clé API est absente, incorrecte ou révoquée. Vérifiez l'en-tête Authorization: Bearer envoyé avec votre requête.

Si vous émettez une nouvelle clé via le tableau de bord, l'ancienne est invalidée immédiatement. Assurez-vous de mettre à jour vos scripts de production en conséquence.

  • Vérifiez la présence de la clé dans l'en-tête HTTP.
  • Générez une nouvelle clé si l'actuelle semble compromise.

Erreur 429 (limite atteinte)

Vous avez dépassé le quota de 60 requêtes par minute par clé. Les requêtes supplémentaires sont refusées jusqu'à ce que le compteur se réinitialise.

Ce mécanisme garantit la stabilité du service. Pour les gros volumes, prévoyez une logique de réessai avec temporisation.

  • Respectez la limite de 60 requêtes/minute.
  • Implémentez une logique de backoff en cas de saturation.

Erreur 500 (synthèse échouée)

Une erreur serveur interne s'est produite lors de la génération audio. La requête n'a pas abouti.

Contrairement aux succès, ces erreurs sont gratuites. Aucun crédit n'est débité pour cette tentative échouée. Vous pouvez réessayer immédiatement.

  • Vérifiez que le texte ne dépasse pas 4096 caractères.
  • Réessayez la requête : le crédit est conservé.

Exemples avancés

Illustration d'onde sonore pour: Exemples avancés

La documentation couvre les aspects techniques clés pour une intégration fluide de l'API VoixRH dans vos outils de e-learning. Cette section détaillera les ajustements avancés pour optimiser la production audio.

Vous trouverez ici des exemples concrets pour gérer la vitesse, les textes longs et les caractères spéciaux, essentiels pour des narrations HR claires.

Ajustement de la vitesse

Vous pouvez ajuster la vitesse de synthèse entre 0.25 et 4.0. Une vitesse plus élevée convient aux annonces rapides, tandis qu'une vitesse réduite améliore la compréhension pour les apprenants.

Cela permet d'adapter le rythme de la narration aux besoins spécifiques de vos formations en ligne.

  • Paramètre speed : 0.25 à 4.0
  • Ajustement fin du rythme de parole
  • Idéal pour diversifier le contenu audio

Textes longs découpés

La limite est de 4096 caractères par requête. Pour les scripts de formation plus longs, découpez le texte en segments et joignez les fichiers audio résultants.

Cette méthode garantit que chaque partie est synthétisée correctement sans perte de qualité.

Le traitement séquentiel peut créer une file d'attente sous charge, prévoyez donc un léger délai pour les gros volumes.

  • Limite : 4096 caractères par requête
  • Découpage manuel ou automatique
  • Assemblage des fichiers audio

Gestion des caractères spéciaux

Les espaces et ponctuations comptent pour le calcul des caractères. Assurez-vous que vos textes HR sont propres avant l'envoi.

L'API gère nativement les caractères UTF-8 courants. Pour les cas particuliers, testez d'abord avec un court extrait.

Une synthèse échouée est gratuite, ce qui permet de valider vos formats sans risque financier.

  • Espaces et ponctuation inclus dans le comptage
  • Support UTF-8 natif
  • Échec gratuit pour les tests

Écoutez les 8 voix

Chaque échantillon ci-dessous a été généré par cette API à partir de la même phrase. La clarté du texte se reflète directement dans la naturalité de la voix générée, réduisant les pauses artificielles.

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. W3C WAI: making audio and video accessible
  3. OpenAI API reference: create speech
  4. ISO 639 language codes
  5. openai-python on GitHub
  6. MDN: Web Speech API
  7. curl documentation
  8. LibriVox public-domain audiobooks
  9. FFmpeg documentation
  10. Node.js documentation
  11. openai-node on GitHub
  12. LibriTTS-R paper (arXiv 2305.18802)

Plus sur ce site