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 — d'abord vos voix clonées et conçues, puis le catalogue public. Utilisez l'id renvoyé comme voice lors de la génération. Les voix du catalogue acceptent aussi leur slug.

Chaque réponse contient total, count, offset et has_more, vous pouvez donc paginer sans deviner. Les mêmes quatre paramètres (sauf type) fonctionnent sur GET /api/v1/voices/clones et GET /api/v1/voices/designs.

curl "https://api.vocallab.ai/api/v1/voices?q=narrator&limit=20" \
  -H "Authorization: Bearer vl_live_..."

{ "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 tous les utiliser. Voir Modèles de voix pour les différences.

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

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, "stream_url": "https://api.vocallab.ai/api/v1/tts/.../audio",
  "captions_url": "https://api.vocallab.ai/api/v1/tts/.../captions",
  "format": "MP3", "model": "v-pro", "points_used": 12 }

Modèle et coût. v-flash est facturé à ¾ (points = ⌈ caractères ÷ 20 ⌉) et v-lite à la moitié (÷ 30) des points de v-pro/v-studio (÷ 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://...",
  "stream_url": "https://api.vocallab.ai/api/v1/tts/.../audio",
  "captions_url": "https://api.vocallab.ai/api/v1/tts/.../captions", "format": "MP3" }

GET /api/v1/tts/:id/audio

Diffusez directement les octets audio du clip finalisé — une alternative au blob base64 audio_base64. Servi inline (lecture dans un navigateur ou un lecteur multimédia) et compatible avec l'en-tête HTTP Range pour permettre le déplacement. Renvoie 409 tant que le clip est en cours de finalisation — interrogez GET /api/v1/tts/:id jusqu'à ce que status soit ready, puis diffusez.

curl -L https://api.vocallab.ai/api/v1/tts/GENERATION_ID/audio \
  -H "Authorization: Bearer vl_live_..." \
  -o speech.mp3

Le même lien est renvoyé comme stream_url par POST /api/v1/tts et GET /api/v1/tts/:id.

GET /api/v1/tts/:id/captions

Les sous-titres d'une génération, sous forme de fichier .srt. Les cues suivent la parole réelle (minutage par mot renvoyé avec la synthèse), et tout balisage [emotion] ou toute pause <break /> est supprimé : seuls les mots prononcés figurent dans le fichier.

Les sous-titres sont construits à partir du minutage enregistré, pas du fichier audio — ils sont disponibles immédiatement, même tant que status vaut encore pending.

curl -L "https://api.vocallab.ai/api/v1/tts/GENERATION_ID/captions" \
  -H "Authorization: Bearer vl_live_..." \
  -o speech.srt

1
00:00:00,000 --> 00:00:01,240
Hello from VocalLab,

2
00:00:01,240 --> 00:00:03,100
this is your narrator speaking.

Avec format=json :

{ "id": "...", "mode": "phrase", "duration": 3.1,
  "srt": "1\n00:00:00,000 --> 00:00:01,240\nHello from VocalLab,\n\n...",
  "words": [ { "word": "Hello", "start": 0, "end": 0.32 } ] }

Le même lien est renvoyé comme captions_url par POST /api/v1/tts et GET /api/v1/tts/:id. Pour récupérer le SRT avec l'audio en un seul appel, envoyez "captions": true sur POST /api/v1/tts.

Renvoie 409 captions_unavailable lorsqu'une génération n'a aucun minutage de mots enregistré (quelques anciens clips) — l'audio n'est pas affecté.

DELETE /api/v1/tts/:id

Supprimez définitivement une génération vous appartenant — à la fois le fichier audio stocké et son enregistrement en base de données. Pratique pour faire le ménage après un téléchargement ou pour honorer une demande de suppression de données. Un id inexistant, ou qui ne vous appartient pas, renvoie 404.

curl -X DELETE https://api.vocallab.ai/api/v1/tts/GENERATION_ID \
  -H "Authorization: Bearer vl_live_..."

{ "ok": true, "id": "...", "deleted": true }

GET /api/v1/voices/languages

Nouveau : GET /api/v1/voices/languages renvoie désormais plus de 470 langues avec leurs variantes d'accent (par exemple en-GB, pt-PT). code est une balise BCP-47 ; les anciennes valeurs (EN_US, PT_BR, …) et Other restent acceptées.

Les langues et les limites d'enregistrement qui s'appliquent au clonage et à la conception de voix. Interrogez cet endpoint plutôt que de coder la liste en dur : c'est la source de vérité qu'utilise le formulaire d'envoi du Studio.

{ "languages": [
    { "name": "English", "code": "EN_US", "experimental": false },
    { "name": "Other",   "code": "AUTO",  "experimental": true }
  ],
  "sample_limits": { "max_samples": 1, "max_base64_length": 4194304,
                     "allowed_formats": ["mp3", "wav", "webm"] } }

Conception de voix

Inventez une voix inédite à partir d'une description écrite, sans le moindre enregistrement. Deux appels : générer des aperçus candidats, puis conserver celui qui vous plaît.

POST /api/v1/voices/designs/previews

Génère jusqu'à trois voix candidates. Facturé en points — chaque aperçu est une véritable synthèse de preview_text au tarif de l'API (⌈caractères ÷ 15⌉ par aperçu).

Rien n'est encore enregistré, donc cet appel n'occupe pas d'emplacement de conception — mais il en exige un libre. Si vos conceptions atteignent déjà la limite de l'offre, l'appel renvoie 409 design_limit et aucun point n'est dépensé : payer pour une voix que vous ne pourriez pas conserver n'aurait aucun sens.

curl -X POST https://api.vocallab.ai/api/v1/voices/designs/previews \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A warm, unhurried British woman in her forties, low and reassuring, like a documentary narrator.","count":2}'

{ "previews": [
    { "preview_id": "...", "text": "Hello! This is a preview of my voice...",
      "preview_url": "https://api.vocallab.ai/api/v1/audio/..." }
  ],
  "points_used": 12, "expires_in": 1800 }

Un preview_id n'est pas encore une voix utilisable, et il reste valable environ 30 minutes.

Les aperçus que vous ne conservez pas sont supprimés. Enregistrez celui que vous voulez avant d'en générer d'autres : rappeler cet endpoint supprime vos aperçus précédents et leurs preview_url cessent de fonctionner, et en enregistrer un supprime le reste de son lot. Dans les deux cas, rien ne subsiste.

POST /api/v1/voices/designs

Conserve un aperçu comme voix permanente. Ne coûte aucun point (les aperçus ont déjà été facturés) mais occupe un emplacement de conception de votre offre. L'id renvoyé s'utilise immédiatement comme voice dans POST /api/v1/tts.

{ "id": "default-abc123__narrator", "name": "Documentary Narrator", "type": "designed",
  "languages": ["EN_US"], "created_at": "...",
  "preview_url": "https://api.vocallab.ai/api/v1/audio/...", "used": 3, "limit": 20 }

GET /api/v1/voices/designs

Vos voix conçues, de la plus récente à la plus ancienne, avec l'occupation des emplacements : { "voices": [...], "used": 3, "limit": 20 }.

DELETE /api/v1/voices/designs/:voiceId

Supprime la voix chez le fournisseur et de votre bibliothèque. Sur une offre payante, cela libère un emplacement. Renvoie { "ok": true, "id": "...", "deleted": true }.

Clonage de voix

Recréez une voix précise à partir d'un court enregistrement. Le clonage ne coûte aucun point : il est uniquement limité par le nombre d'emplacements de clonage de votre offre. Ne clonez que des voix qui vous appartiennent ou pour lesquelles vous avez une autorisation écrite.

POST /api/v1/voices/clones

Presque tous les fichiers audio conviennent. audio_base64 est le base64 brut de votre enregistrement, sans préfixe data: — MP3, WAV, M4A, AAC, OGG, FLAC, WebM, la piste audio d'un MP4, et d'autres. Tout ce que le fournisseur vocal n'accepterait pas directement est converti côté serveur en WAV mono 16 bits, exactement comme les applications web le font dans le navigateur avant l'envoi : l'API n'est donc pas plus exigeante que le Studio.

• tronque aux 30 premières secondes — vous pouvez envoyer un fichier plus long, seul le début est utilisé ;
• mixe la stéréo en mono et rééchantillonne à 32 kHz ;
• réduit les fichiers trop lourds, un gros WAV studio 24 bits n'a donc plus besoin d'être préparé à la main.

La limite porte sur la chaîne base64, pas sur les octets décodés : jusqu'à 8 000 000 de caractères, soit environ un fichier de 6 Mo. Au-delà, l'appel renvoie 413 sample_too_large ; un fichier sans audio lisible renvoie 400 unreadable_audio.

Lorsque quelque chose a été modifié, la réponse contient un tableau audio_notes qui le précise — à journaliser, pour qu'un clone construit sur les 30 premières secondes d'un long enregistrement ne soit jamais une surprise silencieuse :

{ "id": "...", "name": "My Narrator", "type": "clone", "used": 2, "limit": 100,
  "audio_notes": ["Re-encoded to mono 16-bit WAV at 32 kHz — aac isn't a format the provider accepts.",
                  "Trimmed to the first 30s (the sample was 90s)."] }

curl -X POST https://api.vocallab.ai/api/v1/voices/clones \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"My Narrator\",\"language\":\"English\",\"samples\":[{\"audio_base64\":\"$(base64 -w0 sample.mp3)\"}]}"

{ "id": "default-abc123__my-narrator", "name": "My Narrator", "type": "clone",
  "languages": ["EN_US"], "created_at": "...", "used": 2, "limit": 100 }

GET /api/v1/voices/clones

Vos voix clonées, de la plus récente à la plus ancienne, avec l'occupation des emplacements : { "voices": [...], "used": 2, "limit": 100 }.

DELETE /api/v1/voices/clones/:voiceId

Supprime la voix chez le fournisseur et de votre bibliothèque. Sur une offre payante, cela libère un emplacement. Renvoie { "ok": true, "id": "...", "deleted": true }.

Les emplacements sont distincts. Voix clonées et voix conçues ne partagent jamais de budget — voir Offres et limites pour les chiffres de chaque offre. Sur l'offre Free, le plafond est à vie : supprimer une voix ne libère pas l'emplacement. Dans un espace de travail, les membres travaillent dans les limites de l'offre du propriétaire, et les points de conception sont prélevés sur le solde du propriétaire.

Ce qui coûte des points

GET /api/v1/me

Votre solde de points et votre plan.

Erreurs

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