API text to speech: guia com exemplos em Python e JS

Uma API de TTS é um endereço HTTP: você envia um texto e uma voz, e recebe um áudio de volta. Ela faz sentido quando o áudio passa a fazer parte de um processo e deixa de ser uma tarefa avulsa. Se você narra um vídeo por mês, o editor web é mais rápido. Se narra um por dia, ou se o seu produto precisa falar, a API poupa o ciclo de copiar, colar e baixar toda vez.

Os usos que mais vemos:

• Canais do YouTube, inclusive os que não mostram o rosto: o roteiro sai de uma etapa de escrita (muitas vezes um modelo de IA) e vai direto para a narração e de lá para o editor de vídeo.
• Cursos e treinamentos: centenas de aulas curtas que são regeneradas sempre que o texto muda.
• Apps e produtos: avisos, boas-vindas, acessibilidade, botões de “ouvir este artigo”.
• Lotes: fichas de produto, versão em áudio de um blog, menus de atendimento telefônico, o mesmo roteiro em vários idiomas.
• Automações sem código: fluxos do n8n, Make ou Zapier que transformam uma linha nova de uma planilha em um MP3.

Comece pelo que você vai construir, não pela demo da voz. O que divide o mercado é latência contra duração: um assistente de voz precisa da primeira sílaba em poucas centenas de milissegundos e recebe o áudio aos pedaços enquanto ele é gerado, já um narrador precisa que um roteiro de 40 minutos saia em um único arquivo limpo. Poucas APIs fazem bem as duas coisas, e as mais baratas por caractere costumam ser as menos naturais.

Tudo é REST com JSON, com o endereço base https://voizum.com/api/v1 e autenticação por uma chave Bearer que começa com sk_voizum_. O fluxo é sempre o mesmo: criar o trabalho, consultar o status e baixar o MP3.

1. 1Entre na Voizum com o Google e compre qualquer pacote de créditos: a chave é liberada com as duas coisas. A API gasta créditos comprados, nunca os grátis do mês.
2. 2Abra a página de API e gere a sua chave. Ela aparece uma única vez: guarde-a na hora em uma variável de ambiente (VOIZUM_API_KEY) ou no seu gerenciador de segredos.
3. 3Tenha uma voz na sua biblioteca: clone a sua ou salve uma da biblioteca pública com Adicionar. A API só trabalha com as vozes da sua biblioteca.
4. 4Liste-as com GET /voices. Cada uma traz id, name e language; o id é o voice_id que você envia ao gerar. Você também pode copiá-lo na web: Vozes, menu ⋯, ID para a API.
5. 5Opcional: antes de um lote grande, GET /status (público, sem chave) diz se o serviço está no ar, e GET /account mostra o seu saldo e os seus limites.

Os exemplos funcionam do jeito que estão, bastando trocar YOUR_VOICE_ID e JOB_ID. O endereço do áudio devolvido pela consulta de status exige o mesmo cabeçalho Authorization e redireciona para o arquivo, então deixe o seu cliente HTTP seguir os redirecionamentos.

# 1. Criar o trabalho
curl -X POST https://voizum.com/api/v1/tts \
  -H "Authorization: Bearer $VOIZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-042-intro" \
  -d '{"text": "Bem-vindo de volta ao canal.", "voice_id": "YOUR_VOICE_ID"}'

# 2. Consultar o status (repita até "done")
curl https://voizum.com/api/v1/tts/JOB_ID -H "Authorization: Bearer $VOIZUM_API_KEY"

# 3. Baixar o MP3
curl -L -o narracao.mp3 https://voizum.com/api/v1/tts/JOB_ID/audio -H "Authorization: Bearer $VOIZUM_API_KEY"

import os, time, requests

API = "https://voizum.com/api/v1"
H = {"Authorization": "Bearer " + os.environ["VOIZUM_API_KEY"]}

# 1. Criar o trabalho
with open("roteiro.txt", encoding="utf-8") as f:
    texto = f.read()
r = requests.post(API + "/tts", headers=H, json={"text": texto, "voice_id": "YOUR_VOICE_ID"})
r.raise_for_status()
job = r.json()["job_id"]

# 2. Esperar enquanto está na fila ou sendo gerado
while True:
    s = requests.get(API + "/tts/" + job, headers=H).json()
    if s["status"] not in ("queued", "processing"):
        break
    time.sleep(5)
if s["status"] != "done":
    raise RuntimeError(s.get("error", s["status"]))

# 3. Baixar o MP3
audio = requests.get(s["audio_url"], headers=H)
audio.raise_for_status()
with open("narracao.mp3", "wb") as f:
    f.write(audio.content)

import fs from "node:fs";

const API = "https://voizum.com/api/v1";
const H = { Authorization: "Bearer " + process.env.VOIZUM_API_KEY, "Content-Type": "application/json" };

// 1. Criar o trabalho
const crear = await fetch(API + "/tts", {
  method: "POST",
  headers: H,
  body: JSON.stringify({ text: "Bem-vindo de volta ao canal.", voice_id: "YOUR_VOICE_ID" }),
});
if (!crear.ok) throw new Error(await crear.text());
const { job_id } = await crear.json();

// 2. Esperar enquanto está na fila ou sendo gerado
let s;
do {
  await new Promise((r) => setTimeout(r, 5000));
  s = await (await fetch(API + "/tts/" + job_id, { headers: H })).json();
} while (s.status === "queued" || s.status === "processing");
if (s.status !== "done") throw new Error(s.error ?? s.status);

// 3. Baixar o MP3
const audio = await fetch(s.audio_url, { headers: H });
fs.writeFileSync("narracao.mp3", Buffer.from(await audio.arrayBuffer()));

Uma requisição aceita até 600.000 caracteres, cerca de 10 horas de voz, e volta como um único MP3. Não é preciso dividir o roteiro e emendar os pedaços: o trabalho faz isso por dentro e a consulta de status mostra o andamento (parts_done, parts_total, percent).

Para muitas peças curtas, use POST /tts/batch: até 100 áudios e 1.200.000 caracteres no total (cerca de 20 horas). Cada um sai com o seu job_id e o seu arquivo, mas o mínimo de 100 créditos é cobrado uma vez para o lote inteiro, e não uma por requisição. Oito avisos curtos de um app custam 800 créditos enviados um a um e 100 em lote.

Para uma conversa em um único arquivo (a abertura de um podcast, um anúncio com duas vozes) existe POST /tts/dialogue, com as falas em ordem e até 5 vozes diferentes. É cobrado como um áudio normal, pelos caracteres do roteiro todo.

A clonagem é feita uma vez na web e custa 199 créditos; depois disso a voz é só mais um voice_id e cada áudio é cobrado como com qualquer outra voz. Não há endpoint de clonagem na API de propósito: a gravação é a etapa em que vale a pena ouvir antes de seguir em frente. Grave de 15 a 60 segundos só com a sua voz, corte numa pausa e não no meio de uma palavra, e fale do jeito que quer que a narração soe, porque a entonação também é copiada.

Suas vozes clonadas falam os sete idiomas, então uma gravação em português também narra a versão em inglês, alemão ou francês do seu canal. Clone apenas a sua voz ou uma que você tenha permissão para usar.

Nenhuma plataforma de automação precisa de um módulo especial da Voizum: as três têm uma etapa HTTP genérica, e a API são três chamadas simples. A única decisão é como esperar pelo áudio: consultar em loop ou deixar a API avisar você com webhook_url.

O aviso (apenas em POST /tts) envia um POST com event, id, status (completed ou error), voice_id, duration_seconds e credits quando o trabalho termina, com até três tentativas. Precisa ser um endereço https público, então um n8n instalado na sua máquina com localhost não consegue recebê-lo: nesse caso, consulte em loop.

Todos os erros têm o mesmo formato, { error: { code, message } }. Programe com base em code, que é estável, nunca em message, que é um texto para pessoas e pode mudar.

• Envie uma Idempotency-Key em cada POST /tts (o id do seu vídeo ou da sua linha serve). Se um erro de rede obrigar você a tentar de novo, você recebe o mesmo trabalho com um 200 e não é cobrado duas vezes.
• Guarde o job_id assim que o receber. Se o seu processo cair, GET /tts lista os seus trabalhos recentes com um cursor, e você pode filtrar com ?status=done.
• Consulte a cada poucos segundos, ou espere o que eta_seconds indicar, em vez de perguntar sem pausa.
• Baixe e guarde a sua cópia: o MP3 é mantido por 4 dias e depois o arquivo é apagado.
• Errou? DELETE /tts/{id} cancela um trabalho que ainda está na fila e devolve o valor inteiro. Se já está sendo gerado, não dá para cancelar. Se um trabalho termina em erro, os créditos são devolvidos automaticamente.
• Nunca chame a API pelo navegador ou por um app de celular: qualquer pessoa veria a chave. Chame-a pelo seu servidor e faça o seu front-end falar com o seu servidor.
• Troque a chave se suspeitar que vazou. Ao gerar uma nova, a anterior é revogada na hora, então atualize a variável de ambiente logo em seguida.

A API gasta os mesmos créditos que a web: 60 créditos a cada 1.000 caracteres (cerca de 60 por minuto de áudio), com um mínimo de 100 por requisição. Uma narração de 10 minutos para o YouTube tem cerca de 9.850 caracteres, ou seja, 591 créditos. Funciona apenas com créditos comprados, que não expiram e não vêm com assinatura; os créditos grátis do mês que a conta Google dá são só para o gerador web.

Abaixo, o que custa um minuto de áudio no plano mais barato de cada serviço, conforme publicado em setembro de 2026. A Voizum aparece com o pacote Máxi, o de melhor preço por crédito. Tudo em euros para poder comparar.

Se o que você quer é gerar áudio enquanto conversa com o Claude ou o ChatGPT, não precisa da API: o conector da Voizum dá ao assistente ferramentas para gerar e listar vozes, entra com a sua conta e segue as regras da web, créditos grátis do mês incluídos. Dá para configurar em alguns minutos pela página Conectar.

E se você só precisa que uma página leia um texto em voz alta no navegador de quem a visita, basta a Web Speech API que os navegadores já trazem. É grátis, mas soa robótica, muda de um dispositivo para outro e não entrega nenhum arquivo. Uma API de texto para voz vale a pena quando você precisa de uma voz natural em um MP3 que possa publicar.