Referência da API

URL base https://api.vocallab.ai. Toda requisição precisa de Authorization: Bearer vl_live_... (veja Chaves de API).

GET /api/v1/ping

Teste de conexão + autenticação. Retorna seu saldo de pontos.

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

GET /api/v1/voices

Vozes que você pode usar — o catálogo público mais suas próprias vozes clonadas e criadas. Use um id retornado como o voice para a geração. Vozes do catálogo também aceitam o 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

Os modelos de fala selecionáveis. Passe uma key como model em POST /api/v1/tts (padrão v-pro). As chaves de API podem usar os três. Veja Modelos de Voz para as diferenças.

{ "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

Gera fala.

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"}'

Retorna o áudio inline (base64) mais um id. A URL hospedada aparece assim que o upload termina — consulte GET /api/v1/tts/:id para obtê-la.

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

Modelo e custo. O v-lite é cobrado pela metade dos pontos do v-pro/v-studio (points = ⌈ caracteres ÷ 30 ⌉ em vez de ÷ 15). O v-studio é o único modelo que segue instruções de expressão/direcionamento — veja Modelos de Voz e Direcionamento de Voz.

Pausas

Insira um silêncio de duração exata com uma tag <break /> autofechável diretamente em text:

{ "text": "Deixe-me pensar <break time=\"1.5s\" /> Sim, já pensei nisso.", "voice": "Ashley" }

• Segundos ou milissegundos — 1.5s = 1500ms.
• Até 20 tags break por requisição, em todos os idiomas suportados.
• Tags break contam para o limite de 2.000 caracteres e são removidas das legendas/SRT.

GET /api/v1/tts/:id

Status da geração e a URL do áudio hospedado quando estiver pronto.

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

GET /api/v1/me

Seu saldo de pontos e plano.

Erros

Os erros têm o formato { "error": { "code": "...", "message": "..." } }.

Preços

As gerações são cobradas do seu saldo de pontos, calculado a partir do comprimento do texto (não da duração final do áudio):

points = ⌈ characters ÷ 15 ⌉      (taxa da API — cerca de 15 caracteres por ponto)

⌈ ⌉ arredonda para cima até o próximo ponto inteiro. O aplicativo web usa 17 caracteres por ponto, então a API tem um pequeno prêmio (~13%). Os pontos são medidos antes da chamada upstream — uma requisição que ultrapassaria seu saldo retorna 402 e nunca é gerada. Cada resposta inclui o points_used exato. Como a fala tem, em média, ~15–17 caracteres/segundo, 1 ponto ≈ 1 segundo de áudio, mas a cobrança exata sempre segue a fórmula acima. Veja Créditos e Minutos para mais detalhes.