Référence de l'API

URL de base https://api.vocallab.ai. Chaque requête nécessite Authorization: Bearer vl_live_... (voir Clés d'API).

GET /api/v1/ping

Test de connexion + authentification. Renvoie votre solde de points.

{ "ok": true, "points": 12345, "unit": "points (1 pt ≈ 1 second of audio)" }

GET /api/v1/voices

Les voix que vous pouvez utiliser — le catalogue public ainsi que vos propres voix clonées et conçues. Utilisez un id renvoyé comme valeur voice pour la génération. Les voix du catalogue acceptent aussi leur slug.

{ "voices": [
  { "id": "Ashley", "slug": "warm-natural-female-explainer-voice-for-youtube-podcasts",
    "name": "Warm Natural Female Explainer Voice for YouTube & Podcasts",
    "type": "preset", "languages": ["en"], "category": "Narration" },
  { "id": "default-abc123__my-voice", "name": "My Narrator", "type": "clone", "languages": ["en"] }
] }

GET /api/v1/models

Les modèles de voix sélectionnables. Passez une key comme valeur model sur POST /api/v1/tts (par défaut v-pro). Les clés d'API peuvent utiliser les trois. Voir Modèles de voix pour les différences.

{ "default": "v-pro", "models": [
  { "key": "v-studio", "label": "VocalLab Studio", "steerable": true,  "costMultiplier": 1 },
  { "key": "v-pro",    "label": "VocalLab Pro",    "steerable": false, "costMultiplier": 1 },
  { "key": "v-lite",   "label": "VocalLab Lite",   "steerable": false, "costMultiplier": 0.5 }
] }

POST /api/v1/tts

Générer de la voix.

curl -X POST https://api.vocallab.ai/api/v1/tts \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from VocalLab","voice":"Ashley"}'

Renvoie l'audio en ligne (base64) ainsi qu'un id. L'URL hébergée apparaît une fois le téléversement terminé — interrogez GET /api/v1/tts/:id pour l'obtenir.

Chaque requête est limitée à 2 000 caractères et correspond à exactement une synthèse vocale — il n'y a pas de découpage ni de répartition cachés, de sorte que le coût et la latence par appel restent prévisibles. Les requêtes sont décomptées de votre solde de points et passent par une file d'attente d'usage équitable, afin qu'une automatisation intensive ne bloque jamais l'application. Pour narrer un texte plus long, découpez-le en morceaux de ≤ 2 000 caractères et envoyez-les en tant qu'appels séparés (en respectant la limite de 60 requêtes/minute).

{ "id": "...", "status": "pending", "audio_base64": "data:audio/mp3;base64,...",
  "audio_url": null, "format": "MP3", "model": "v-pro", "points_used": 12 }

Modèle et coût. v-lite est facturé à la moitié des points de v-pro/v-studio (points = ⌈ caractères ÷ 30 ⌉ au lieu de ÷ 15). v-studio est le seul modèle qui suit les instructions d'expression/d'orientation — voir Modèles de voix et Orientation de la voix.

Pauses

Insérez un silence d’une durée exacte avec une balise <break /> auto-fermante directement dans text :

{ "text": "Laissez-moi réfléchir <break time=\"1.5s\" /> Oui, j’y ai réfléchi.", "voice": "Ashley" }

• Secondes ou millisecondes — 1.5s = 1500ms.
• Jusqu’à 20 balises break par requête, dans toutes les langues prises en charge.
• Les balises break comptent dans la limite de 2 000 caractères et sont retirées des sous-titres/SRT.

GET /api/v1/tts/:id

Statut de la génération et URL de l'audio hébergé une fois prêt.

{ "id": "...", "status": "ready", "audio_url": "https://...", "format": "MP3" }

GET /api/v1/me

Votre solde de points et votre plan.

Erreurs

Les erreurs ont la forme { "error": { "code": "...", "message": "..." } }.