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

As vozes que pode usar — primeiro as suas vozes clonadas e criadas, depois o catálogo público. Use o id devolvido como voice ao gerar. As vozes do catálogo também aceitam o seu slug.

Cada resposta traz total, count, offset e has_more, por isso pode paginar sem adivinhar. Os mesmos quatro parâmetros (menos type) funcionam em GET /api/v1/voices/clones e 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"], "language_code": "en-US",
    "accent": "American", "category": "Narration" },
  { "id": "default-abc123__my-voice", "name": "My Narrator", "type": "clone", "languages": ["en-GB"] }
] }

languages é o idioma base e junta todos os sotaques. language_code e accent (apenas nas vozes predefinidas) dizem qual inglês ou português uma voz realmente é — use-os para escolher uma voz de inglês britânico ou de português europeu sem adivinhar pelo nome.

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 todos eles. Veja Modelos de Voz para as diferenças.

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

supportsTemperature e supportsDeliveryMode indicam qual controle de expressividade um modelo realmente respeita — eles não se sobrepõem. Se enviar o errado, ele é rejeitado em vez de ser ignorado em silêncio.

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.

Cada requisição é limitada a 2.000 caracteres e corresponde a exatamente uma síntese de fala — não há divisão nem fan-out ocultos, então o custo e a latência de cada chamada continuam previsíveis. As requisições são contabilizadas no seu saldo de pontos e passam por uma fila de uso justo, para que automações pesadas nunca bloqueiem o app. Para narrar um roteiro mais longo, divida-o em partes de até 2.000 caracteres e envie-as em chamadas separadas (respeitando o limite de 60 requisições por minuto, ou 120 no Max).

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

Modelo e custo. O v-flash é cobrado por ¾ (points = ⌈ caracteres ÷ 20 ⌉) e o v-lite pela metade (÷ 30) dos pontos do v-pro/v-studio (÷ 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:

curl -X POST https://api.vocallab.ai/api/v1/tts \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Let me think <break time=\"1.5s\" /> Yes, I have thought about it.","voice":"Ashley"}'

• Segundos ou milissegundos — <break time="1.5s" /> e <break time="1500ms" /> são idênticos.
• Até 20 tags break por requisição, em todos os idiomas suportados.
• Os nomes das tags não diferenciam maiúsculas de minúsculas, mas a tag deve estar bem formada e ser autofechável.
• Tags break contam para o limite de 2.000 caracteres e são removidas das legendas/SRT.
• Um ritmo mais suave não precisa de tag: vírgulas, pontos, travessões (—) e linhas em branco moldam a entrega. Veja Direção de Voz.

GET /api/v1/tts/:id

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

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

Transmita diretamente os bytes de áudio do clipe finalizado — uma alternativa ao blob base64 audio_base64. Servido inline (reproduz em um navegador ou player de mídia) e compatível com o cabeçalho HTTP Range para permitir avançar. Retorna 409 enquanto o clipe ainda está sendo finalizado: consulte GET /api/v1/tts/:id até que status seja ready e então transmita.

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

O mesmo link é retornado como stream_url em POST /api/v1/tts e GET /api/v1/tts/:id.

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

As legendas de uma geração, como arquivo .srt. Os cues seguem a fala real (marcações de tempo por palavra devolvidas com a síntese), e qualquer marcação [emotion] ou pausa <break /> é removida, de modo que apenas as palavras faladas chegam ao arquivo.

As legendas são construídas a partir das marcações de tempo salvas, não do arquivo de áudio — ficam disponíveis imediatamente, mesmo enquanto status ainda é 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.

Com 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 } ] }

O mesmo link é retornado como captions_url em POST /api/v1/tts e GET /api/v1/tts/:id. Para receber o SRT junto com o áudio em uma única chamada, envie "captions": true em POST /api/v1/tts.

Retorna 409 captions_unavailable quando uma geração não tem marcações de tempo por palavra salvas (alguns clipes mais antigos) — o áudio não é afetado.

DELETE /api/v1/tts/:id

Exclua permanentemente uma geração que você possui — tanto o arquivo de áudio armazenado quanto seu registro no banco de dados. Útil para limpar após um download ou atender a uma solicitação de exclusão de dados. Um id que não existe, ou que não é seu, retorna 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

Os idiomas e os limites de gravação aplicados à clonagem e ao design de voz. Consulte aqui em vez de fixar a lista no código: é a mesma fonte de verdade que o formulário de envio do Studio usa.

São devolvidos mais de 470 idiomas, cada um com as variantes de sotaque que oferece. code é uma etiqueta BCP-47; passe o código do próprio idioma ou um dos seus códigos de sotaque como language ao clonar ou criar uma voz.

experimental: true significa que o idioma não tem catálogo de vozes próprio — a clonagem e o design continuam a funcionar, mas a qualidade varia mais.

{ "languages": [
    { "name": "Auto-detect", "code": "auto", "experimental": true, "accents": [] },
    { "name": "English", "code": "en", "experimental": false, "accents": [
        { "name": "American", "code": "en-US" },
        { "name": "British",  "code": "en-GB" },
        { "name": "Indian",   "code": "en-IN" }
      ] },
    { "name": "Portuguese", "code": "pt", "experimental": false, "accents": [
        { "name": "Brazilian", "code": "pt-BR" },
        { "name": "European",  "code": "pt-PT" }
      ] }
  ],
  "sample_limits": { "max_samples": 1, "max_base64_length": 4194304,
                     "allowed_formats": ["mp3", "wav", "webm"] } }

Alterado: code era um enum de 16 valores (EN_US, PT_BR, …) com uma entrada Other que significava "deixe o motor adivinhar". Esses valores antigos continuam a ser aceites em qualquer lugar onde se indique um language, por isso as integrações existentes continuam a funcionar — mas a lista de onde vinham é agora o conjunto completo, e Other é a entrada explícita auto.

Design de voz

Invente uma voz totalmente nova a partir de uma descrição escrita, sem gravar nada. São duas chamadas: gerar pré-visualizações candidatas e guardar a preferida.

POST /api/v1/voices/designs/previews

Gera até três vozes candidatas. Cobrado em points — cada pré-visualização é uma síntese real de preview_text à tarifa da API (⌈caracteres ÷ 15⌉ por pré-visualização).

Ainda não se guarda nada, por isso isto não ocupa um lugar de design — mas exige um livre. Se os seus designs já estiverem no limite do plano, a chamada devolve 409 design_limit e não se gasta nenhum point, porque não faz sentido pagar por uma voz que não poderia guardar.

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 }

Um preview_id ainda não é uma voz utilizável e é válido durante cerca de 30 minutos.

As pré-visualizações que não guardar são descartadas. Guarde a que quer antes de gerar outro lote — chamar este endpoint outra vez descarta as pré-visualizações anteriores e os seus preview_url deixam de funcionar, e guardar uma descarta o resto do lote. Em qualquer dos casos não fica nada para trás.

POST /api/v1/voices/designs

Guarda uma pré-visualização como voz permanente. Não custa points (as pré-visualizações já foram cobradas), mas ocupa um dos lugares de design do seu plano. O id devolvido funciona logo como voice em POST /api/v1/tts.

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

GET /api/v1/voices/designs

As suas vozes criadas, da mais recente para a mais antiga, com o uso de lugares: { "voices": [...], "used": 3, "limit": 20 }.

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

Apaga a voz do fornecedor e da sua biblioteca. Num plano pago liberta um lugar. Devolve { "ok": true, "id": "...", "deleted": true }.

Clonagem de voz

Recrie uma voz específica a partir de uma gravação curta. Clonar não custa points — está limitado apenas pelo número de lugares de clonagem do seu plano. Clone apenas vozes que lhe pertençam ou para as quais tenha autorização por escrito.

POST /api/v1/voices/clones

Quase qualquer ficheiro de áudio serve. audio_base64 é o base64 puro da sua gravação, sem prefixo data: — MP3, WAV, M4A, AAC, OGG, FLAC, WebM, a faixa de áudio de um MP4 e mais. Tudo o que o fornecedor de voz não aceitaria diretamente é convertido no servidor para WAV mono de 16 bits, tal como as apps web fazem no navegador antes de enviar — por isso a API não é mais exigente do que o Studio.

A conversão também:

• corta aos primeiros 30 segundos — pode enviar um ficheiro mais longo, mas só o início é usado;
• mistura estéreo para mono e reamostra para 32 kHz;
• reduz ficheiros demasiado grandes, por isso um WAV de estúdio de 24 bits já não tem de ser preparado à mão.

O limite aplica-se à string base64, não aos bytes descodificados: até 8 000 000 de caracteres, cerca de um ficheiro de 6 MB. Acima disso devolve 413 sample_too_large; um ficheiro sem áudio legível devolve 400 unreadable_audio.

Quando algo foi alterado, a resposta inclui um array audio_notes a dizê-lo — vale a pena registar, para que um clone feito dos primeiros 30 segundos de uma gravação longa nunca seja uma surpresa silenciosa:

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

As suas vozes clonadas, da mais recente para a mais antiga, com o uso de lugares: { "voices": [...], "used": 2, "limit": 100 }.

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

Apaga a voz do fornecedor e da sua biblioteca. Num plano pago liberta um lugar. Devolve { "ok": true, "id": "...", "deleted": true }.

Os lugares são separados. Vozes clonadas e criadas nunca partilham orçamento — veja Planos e limites para os números de cada plano. No plano Free o limite é vitalício: apagar uma voz não liberta o lugar. Num espaço de trabalho, os membros trabalham dentro dos limites do plano do proprietário, e os points de design saem do saldo do proprietário.

O que custa points

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.