Voizum

API de texto para voz: suas vozes, direto do seu código

Uma API REST simples: você envia um texto e uma das suas vozes e recebe o MP3. Usa os mesmos créditos do site, sem taxa de desenvolvedor nem custo por chamada.

URL base
https://voizum.com/api/v1
Vídeos (v3)
https://voizum.com/api/v3
Autenticação
Bearer sk_voizum_…
Saída
MP3 · MP4
Idiomas
es · en · de · fr · pt · it · ru · nl · pl · zh · ja · ko · hi · ar · tr · id · ro
Preço
60 créditos / 1.000 caracteres (mín. 100)

Para assistentes de IA e ferramentas

Três caminhos, conforme quem se conecta. Todos levam ao mesmo lugar: suas vozes e seus créditos.

Claude, ChatGPT, Cursor… sem programar
O conector MCP: adicione ao assistente e peça áudios no chat.
https://voizum.com/mcp
ChatGPT Actions, Postman, geradores de clientes
Importe a especificação OpenAPI 3.1: ela descreve todos os endpoints e seus campos.
https://voizum.com/openapi.json
Agentes que leem documentação
llms.txt: o contrato inteiro em texto simples, feito para modelos de linguagem.
https://voizum.com/llms.txt

Comece em três passos

  1. Crie sua conta e sua chave na seção API do site. A chave começa com sk_voizum_ e é mostrada uma única vez: guarde-a como segredo, nunca no código do navegador.
  2. Escolha uma voz: clone a sua ou adicione a “Minhas vozes” uma da biblioteca. GET /voices devolve o id dela.
  3. Crie o áudio com POST /tts, consulte o status a cada poucos segundos e baixe quando estiver pronto (ou receba um webhook).

Um exemplo completo

Criar, aguardar e baixar. A API é assíncrona: um áudio longo demora a ficar pronto e assim você não precisa manter a conexão aberta.

curl

# 1. Create the audio
curl -X POST https://voizum.com/api/v1/tts \
  -H "Authorization: Bearer $VOIZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hi, this is Voizum.", "voice_id": "VOICE_ID"}'
# → {"job_id": "…", "status": "queued", "credits_charged": 100, "eta_seconds": 20}

# 2. Check the status (until "done")
curl https://voizum.com/api/v1/tts/JOB_ID -H "Authorization: Bearer $VOIZUM_API_KEY"

# 3. Download the MP3
curl -L -o audio.mp3 "https://voizum.com/api/v1/tts/JOB_ID/audio?download=1" -H "Authorization: Bearer $VOIZUM_API_KEY"

Python

import os, time, requests

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

job = requests.post(f"{API}/tts", headers=H, json={"text": "Hi, this is Voizum.", "voice_id": "VOICE_ID"}).json()
while True:
    status = requests.get(f"{API}/tts/{job['job_id']}", headers=H).json()
    if status["status"] in ("done", "error", "canceled"):
        break
    time.sleep(3)

if status["status"] == "done":
    mp3 = requests.get(f"{API}/tts/{job['job_id']}/audio?download=1", headers=H)
    open("audio.mp3", "wb").write(mp3.content)

JavaScript (Node 18+)

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

const job = await (await fetch(`${API}/tts`, {
  method: "POST", headers: H,
  body: JSON.stringify({ text: "Hi, this is Voizum.", voice_id: "VOICE_ID" }),
})).json();

let status;
do {
  await new Promise((r) => setTimeout(r, 3000));
  status = await (await fetch(`${API}/tts/${job.job_id}`, { headers: H })).json();
} while (!["done", "error", "canceled"].includes(status.status));

if (status.status === "done") {
  const mp3 = await fetch(`${API}/tts/${job.job_id}/audio?download=1`, { headers: H });
  await (await import("node:fs/promises")).writeFile("audio.mp3", Buffer.from(await mp3.arrayBuffer()));
}

Endpoints

Método e rotaO que faz
GET /statusEstado do serviço. Sem chave.
GET /accountSeu saldo de créditos e o preço por caractere.
GET /voicesAs vozes da sua biblioteca: o id delas é o voice_id.
GET /libraryBusca na biblioteca pública (filtros: query, language, gender, age, style, accent, limit, offset). Cada voz informa o seu source: voizum ou community.
POST /library/{voice_id}Guarda uma voz pública na sua biblioteca (grátis) e devolve o SEU voice_id para usar em POST /tts. 201 se for nova, 200 se já a tinha; 409 biblioteca_llena.
POST /ttsCria um áudio a partir de um texto.
GET /tts/{job_id}Status do áudio: queued, processing, done, error ou canceled.
GET /tts/{job_id}/audioO MP3 pronto (redireciona para o arquivo; ?download=1 para baixar).
GET /tts/{job_id}/timestampsQuando soa cada frase e cada palavra do MP3, em segundos. Sem custo.
GET /tts/{job_id}/subtitlesAs legendas prontas: ?format=srt (padrão) ou vtt; ?download=1 para baixar.
DELETE /tts/{job_id}Cancela um áudio que ainda não começou: os créditos são devolvidos.
GET /ttsSeus últimos áudios, paginados.
POST /tts/batchVários áudios separados em uma requisição, com um único mínimo (de 2 a 100).
POST /tts/dialogueUm áudio com várias vozes em turnos (até 5 vozes).

Vídeos com avatar (API v3)

Um dos seus avatares dizendo o que você quiser, em um MP4 horizontal (16:9) ou vertical (9:16). Tem a sua própria URL base e usa a mesma chave, no cabeçalho X-Api-Key. As respostas vêm dentro de { "data": … }.

https://voizum.com/api/v3
  1. Prepare o avatar e as cenas dele no site, ou envie com POST /avatars. GET /avatars devolve o id de cada um.
  2. Peça o vídeo com POST /videos, ou vários de uma vez com POST /videos/batches.
  3. Aguarde: consulte GET /videos/{id} a cada poucos segundos, GET /videos/statuses para vários, ou envie callback_url e nós avisamos. Um vídeo leva alguns minutos.
  4. Quando o status for completed, baixe o MP4 de video_url (com a sua chave).

Um vídeo do começo ao fim

# 1. Seus avatares e as cenas (id e scene)
curl https://voizum.com/api/v3/avatars -H "X-Api-Key: $VOIZUM_API_KEY"

# 2. Pedir o vídeo
curl -X POST https://voizum.com/api/v3/videos \
  -H "X-Api-Key: $VOIZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"avatar_id": "AVATAR_ID", "scene": 1, "script": "Olá, eu sou o seu avatar.", "voice_id": "VOICE_ID", "aspect_ratio": "9:16"}'
# → {"data": {"id": "VIDEO_ID", "status": "pending", "credits": …, …}}

# 3. Consultar o status (até "completed"; leva alguns minutos)
curl https://voizum.com/api/v3/videos/VIDEO_ID -H "X-Api-Key: $VOIZUM_API_KEY"
# → {"data": {"status": "completed", "video_url": "https://voizum.com/api/v3/videos/VIDEO_ID/video", …}}

# 4. Baixar o MP4
curl -L -o video.mp4 https://voizum.com/api/v3/videos/VIDEO_ID/video -H "X-Api-Key: $VOIZUM_API_KEY"

Avatares e cenas

Um avatar é uma pessoa. As cenas dele são fotos dessa mesma pessoa (outro enquadramento, outra roupa, outro lugar), numeradas 1, 2, 3… A 1 é a principal, e os números não mudam se você apagar uma.

Um vídeo escolhe avatar_id e scene (sem scene, a 1). Você também pode enviar o id de uma cena como avatar_id, sem scene.

Para enviar uma foto com POST /avatars é preciso mandar "consent": true: é o seu rosto ou você tem a permissão dessa pessoa. Sem avatar_id cria um avatar (com o name, obrigatório: até 40 caracteres e diferente dos seus outros avatares); com avatar_id, adiciona a próxima cena. Até 15 avatares e 10 cenas por avatar.

Os avatares da biblioteca da Voizum são salvos nos favoritos pelo site e aparecem em GET /avatars com uma única cena.

O que ele diz: três formas

script + voice_id: o texto e uma das suas vozes (GET /voices). Primeiro a voz é feita e depois o vídeo; o áudio está incluído no preço.

audio_id: o job_id de um áudio que você já fez com POST /tts (API v1). Assim você o ouve antes e só o vídeo é cobrado.

audio_url: um áudio seu (mp3, wav, m4a, ogg ou webm) em uma URL https pública.

O que o POST /videos aceita

CampoO que é
avatar_idObrigatório (exceto com segments). Um dos seus avatares (GET /avatars), ou o id de uma cena.
sceneOpcional. Qual cena do avatar: por padrão, a 1.
segmentsEm vez de avatar_id: várias partes (até 20) unidas em um só MP4, cada uma com o seu avatar_id, scene e o que diz. Veja «Um vídeo com várias partes».
script + voice_idO que ele diz (até 600.000 caracteres) e com qual voz sua. Opcional: voice_settings.speed, de 0.5 a 2.
audio_idEm vez de script: o job_id de um áudio seu já pronto (POST /tts da API v1).
audio_urlEm vez de script: um áudio seu (mp3, wav, m4a, ogg ou webm) em uma URL https pública.
aspect_ratioOpcional. "16:9" (padrão) ou "9:16".
resolutionOpcional. "1080p" (padrão, a melhor qualidade) ou "720p" (mais rápido e mais barato, pode ficar menos nítido).
emotionOpcional. O rosto: "smile" sorri um pouco quase o tempo todo; "serious", expressão séria e serena. Sem ela, natural e calmo. Mesmo preço.
movementOpcional. O corpo: "still" quase não mexe os braços; "expressive" gesticula mais. Sem ele, algum gesto natural de vez em quando. Mesmo preço.
callback_urlOpcional. Uma URL https pública: avisamos com um POST quando terminar.
callback_idOpcional. A sua própria referência: volta no vídeo e no aviso.
Idempotency-KeyCabeçalho opcional. Repetindo a requisição com a mesma, você recebe o mesmo vídeo sem nova cobrança.

Um vídeo com várias partes

Em vez de avatar_id, envie segments: uma lista de partes (até 20), cada parte com o seu avatar, a sua cena e o que diz (avatar_id, scene e script + voice_id, audio_url ou audio_id). Elas são unidas em ordem em um só MP4.

aspect_ratio, resolution, emotion, movement e callback_url ficam fora da lista e valem para o vídeo inteiro. É cobrado como um vídeo da duração total, com um único mínimo.

curl -X POST https://voizum.com/api/v3/videos \
  -H "X-Api-Key: $VOIZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "segments": [
      {"avatar_id": "AVATAR_ID", "scene": 1, "script": "Olá, eu sou a Lucía.", "voice_id": "VOICE_ID"},
      {"avatar_id": "AVATAR_ID", "scene": 3, "script": "E esta é a novidade deste mês.", "voice_id": "VOICE_ID"}
    ],
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }'

Vários vídeos

Para fazer vários, envie juntos com POST /videos/batches: { "videos": [ … ] }, cada um com os mesmos campos do POST /videos. O mínimo é um só para tudo o que você pede ao mesmo tempo: se juntos passam dele, nenhum o paga. Se um falhar (saldo, avatar…), volta com o seu erro e os outros seguem. Com Idempotency-Key, repetir o mesmo lote devolve os mesmos vídeos sem nova cobrança.

Seus vídeos começam por ordem de chegada e, se houver espaço, vários são feitos ao mesmo tempo; quando outros clientes também esperam, o espaço é dividido entre todos. Enquanto um está em pending, você pode cancelá-lo com DELETE /videos/{id} e os créditos são devolvidos; já em processing, não.

Há um limite de vídeos não terminados ao mesmo tempo: se passar dele, a resposta é concurrency_limit e basta esperar algum terminar.

Preço e armazenamento

resolution "1080p" (padrão, a melhor qualidade): 3450 créditos por minuto de vídeo. "720p" (mais rápido e mais barato, pode ficar menos nítido): 2000. Depende do avatar: teste as duas com cada um.

Cada vídeo custa no mínimo 1500 créditos; se durar mais de 26 s em 1080p ou 45 s em 720p, paga só os seus segundos. Se você pede vários de uma vez, o mínimo é um só para todos: se juntos passam dele, não se paga. Com script, soma-se o áudio como um normal. Até 35 minutos por vídeo e só com créditos comprados.

POST /videos/estimate diz quanto custaria sem criar nada. A cobrança é feita ao pedir; se o vídeo falhar, tudo é devolvido. Com script, a duração é estimada pelos caracteres e ajustada ao medir a voz real.

O MP4 fica guardado 4 dias: baixe e guarde você mesmo.

Callback

Com callback_url enviamos um POST quando o vídeo termina, com sucesso ou não (3 tentativas, 10 s de espera em cada uma). O que importa vem em event_type e event_data; url baixa o MP4 com a sua chave.

O aviso não é assinado: use-o como sinal para consultar GET /videos/{id} com a sua chave, que é a fonte da verdade.

{
  "event_type": "avatar_video.success",
  "event_data": {
    "video_id": "VIDEO_ID",
    "callback_id": "MY_REF",
    "url": "https://voizum.com/api/v3/videos/VIDEO_ID/video"
  }
}

Endpoints de vídeo

Método e rotaO que faz
GET /users/meVerifica a chave: seu saldo, os preços do vídeo e seus limites.
GET /voicesAs vozes da sua biblioteca (o voice_id delas).
GET /avatarsSeus avatares com as cenas, e seus favoritos da biblioteca.
POST /avatarsEnvia uma foto: um avatar novo ou mais uma cena de um seu (com consent).
GET /avatars/{id}Um avatar com as suas cenas.
PATCH /avatars/{id}Muda o nome.
DELETE /avatars/{id}Apaga o avatar com todas as cenas (os vídeos feitos ficam).
DELETE /avatars/scenes/{id}Apaga uma cena; as outras mantêm o número.
POST /videosCria um vídeo.
POST /videos/batchesVários vídeos em uma requisição, com um só mínimo para todos.
POST /videos/estimateQuantos créditos custaria, sem criar nem cobrar.
GET /videos/{id}Status: pending, processing, completed, failed ou canceled.
GET /videos/statuses?ids=a,bO status de até 100 vídeos de uma vez.
GET /videosSeus vídeos, do mais novo ao mais antigo (limit e token).
DELETE /videos/{id}Cancela um vídeo que ainda está em pending: os créditos são devolvidos.
GET /videos/{id}/videoO MP4 pronto (redireciona para o download).

Erros dos vídeos

No formato { "error": { "code", "message", "param", "request_id" } }: param é o campo com problema (se houver) e request_id também vem no cabeçalho X-Request-Id. As mensagens estão em inglês.

CódigoHTTPO que aconteceu
unauthorized401Missing or invalid API key (X-Api-Key header).
invalid_parameter400A field is missing or invalid: param says which.
consent_required400Uploading a photo needs "consent": true.
download_failed400file.url couldn't be downloaded.
file_too_large413The photo is too large.
limit_reached400You reached the maximum number of avatars or scenes per avatar.
invalid_audio400 · 413The audio can't be used (format, size or download failed).
video_too_long400The video exceeds the maximum length (max_seconds says which).
insufficient_credit402Not enough credits (credits_needed, credits_available and buy_credits_url to get more).
purchase_required403Videos need an account that has bought credits.
avatar_not_found404The avatar (or scene) isn't one of yours.
voice_not_found404The voice isn't in your library.
audio_not_found404No finished audio of yours with that audio_id (or it expired).
not_found404The video or scene doesn't exist (or isn't yours).
voice_not_ready409That voice can't be used yet.
unreadable_text422The script has nothing to read aloud: only emojis, symbols or an alphabet the voice can't pronounce.
name_taken409You already have an avatar with that name: pick another one.
main_scene409Scene 1 can't be deleted on its own: delete the whole avatar.
resource_in_use409A video is being made with it: delete it when it finishes.
video_not_cancelable409Only a pending video can be canceled.
rate_limit_exceeded429Too many requests: wait for Retry-After.
concurrency_limit429Too many unfinished videos: wait for some to finish.
service_unavailable503Avatar videos aren't available right now: retry later.

Vem do HeyGen?

Troque a URL base e a chave. Em vez do id de um look, envie avatar_id + scene (o id da cena também funciona). resolution é "1080p" ou "720p". O resto funciona igual.

O que o POST /tts aceita

CampoO que é
textObrigatório. O texto, até 600.000 caracteres.
voice_idObrigatório. Uma voz da sua biblioteca (GET /voices).
speedOpcional. Velocidade, de 0.5 a 2 (1 = o ritmo natural da voz).
pause_msAceito, mas não muda nada com a Voizum 2: as pausas entre frases são definidas pelo modelo. Para uma pausa concreta, escreva <#1.5#> (segundos) no texto.
<#…#>Marcas dentro do texto, sem custo: <#1.5#> é uma pausa de 1,5 s e <#triste#>, <#risada#>, <#sussurro#>… uma emoção que dura até o fim do parágrafo ou até <#normal#> (em es, en, pt, de e fr).
languageOpcional. auto, es, en, de, fr, pt, it, ru, nl, pl, zh, ja, ko, hi, ar, tr, id, ro. Sem ele, o idioma é deduzido do texto.
loudness_normalizationOpcional. Iguala o volume para que todas as vozes soem com a mesma intensidade.
toneOpcional, só em /tts. O tom do áudio inteiro (nomes em espanhol): tranquilo, suave, susurro, alegre, emocionado, triste, nostalgico, decidido, asustado. Para um trecho, uma marca de emoção no texto.
webhook_urlOpcional. Uma URL https pública para a qual enviamos um POST quando o áudio termina.
Idempotency-KeyCabeçalho opcional. Se você repetir a requisição com a mesma chave, recebe o mesmo áudio e não é cobrado duas vezes.

Webhook

Com webhook_url você não precisa consultar o status: ao terminar, enviamos um POST com o evento generation.finished (3 tentativas, 10 s de espera em cada uma). Se o seu servidor responder com 4xx, não há nova tentativa.

O aviso não é assinado: use-o como sinal para consultar GET /tts/{job_id} com a sua chave, que é a fonte da verdade, e não como prova de que o áudio está pronto.

{
  "event": "generation.finished",
  "id": "JOB_ID",
  "status": "completed",
  "voice_id": "VOICE_ID",
  "duration_seconds": 12.4,
  "credits": 100,
  "error": null
}

Marcações de tempo e legendas

Quando um áudio do Voizum 2 está em done, GET /tts/{job_id} traz timestamps_url e subtitles_url (os áudios anteriores a 17/11/2026 não os têm). A primeira dá cada frase (segments) e cada palavra (words) com o início e o fim em segundos do MP3, com a velocidade já aplicada; a segunda, as legendas em SRT ou WebVTT, uma frase por legenda (dividida se passar de 2 linhas de 42 caracteres ou de 7 segundos). Não custam nada e ficam guardadas o mesmo tempo que o job, mesmo que o MP3 expire antes.

As palavras são as que se ouvem: números, datas e símbolos vêm escritos como se falam («1889» → «mil oitocentos e oitenta e nove») e as marcações (<#1.5#>, <#triste#>) não aparecem. A pontuação vai junto da palavra. Em chinês e japonês cada caractere é uma palavra. Os tempos são uma estimativa bem ajustada: metade das palavras cai a menos de 0,07 s do seu lugar e o início de cada frase, a poucos centésimos.

{
  "job_id": "JOB_ID",
  "duration_seg": 4.2,
  "segments": [
    { "text": "Hola, ¿qué tal?", "start": 0.06, "end": 1.31 },
    { "text": "Bienvenido a Voizum.", "start": 1.92, "end": 4.1 }
  ],
  "words": [
    { "text": "Hola,", "start": 0.06, "end": 0.52 },
    { "text": "¿qué", "start": 0.71, "end": 0.98 },
    { "text": "tal?", "start": 0.98, "end": 1.31 }
  ]
}

Limites

20 criações por minuto (POST /tts, /tts/batch e /tts/dialogue compartilham esse limite) e 300 requisições por minuto por chave no total. As respostas de criação trazem X-RateLimit-Limit e X-RateLimit-Remaining, e todo 429 traz Retry-After com os segundos de espera.

O MP3 fica guardado por 4 dias; depois disso GET /tts/{job_id}/audio retorna 404, então baixe e guarde o arquivo por conta própria.

Um áudio aceita até 600.000 caracteres. Um lote, de 2 a 100 áudios e 1.200.000 caracteres no total. Um diálogo, até 100 turnos e 5 vozes diferentes.

Erros

Sempre no mesmo formato: { "error": { "code", "message" } }, às vezes com detalhes (por exemplo, quantos créditos faltam). As mensagens estão em inglês.

CódigoHTTPO que aconteceu
no_autorizado401Missing or invalid API key.
parametros_invalidos400Missing fields or invalid values.
cuerpo_invalido400The body is not valid JSON.
texto_demasiado_largo400The text exceeds the character limit.
lote_invalido400A batch takes 2 to 100 items.
dialogo_invalido400A dialogue takes 2 to 100 turns and up to 5 voices.
webhook_invalido400webhook_url is not https or not a public host.
voz_sin_muestra400That voice can't be used yet.
texto_ilegible422The text has nothing to read aloud: only emojis, symbols or an alphabet the voice can't pronounce. Anything else (decorative letters, stray emojis, formatting) is cleaned up automatically.
idioma_no_disponible422That language can't be generated right now (only if the service temporarily falls back to the previous model with one of the new languages; the message lists the available ones). A text in a language we don't offer is NOT rejected: it is generated anyway.
saldo_insuficiente402Not enough credits (the response says how many are needed and includes buy_credits_url to get more).
requiere_compra403Batches and videos need an account that has bought credits.
voz_no_encontrada404The voice is not in your library.
biblioteca_llena409You already have the maximum number of saved voices: remove one in the web app to add another from the library.
no_encontrado404No job with that id (or it isn't yours).
marcas_no_disponibles404That audio has no timestamps: it hasn't finished yet or they aren't available for it.
limite_peticiones429Too many requests: wait for Retry-After.
demasiados_en_cola429Too many jobs in progress: wait for some to finish.
mantenimiento503Maintenance pause: retry later.
servicio_no_disponible503Service temporarily unavailable: retry.

Perguntas

Existe SDK para Python ou JavaScript?
Não precisa: são poucas chamadas REST com JSON, que funcionam com qualquer cliente HTTP (requests, fetch, curl). Se quiser um cliente gerado, a especificação OpenAPI cria um na sua linguagem.
Existe streaming em tempo real?
Não. A API é assíncrona: você cria o áudio, consulta o status e baixa o MP3 pronto. Ela serve para narrações, vídeos, cursos e conteúdo, não para conversa ao vivo.
Posso usar as vozes da biblioteca?
Sim, em dois passos: busque com GET /library e guarde a que gostar com POST /library/{voice_id} (ou adicione pelo site); devolve o SEU voice_id para POST /tts. A API só gera com vozes suas. As marcadas source: community foram enviadas por outros usuários: a Voizum não verifica nem se responsabiliza pela origem delas; use por sua conta e risco e respeite os direitos da pessoa dona da voz.
Dá para clonar uma voz pela API?
Não: a clonagem é feita pelo site (você envia a gravação uma vez) e depois você usa a voz pela API com o voice_id dela.
Quanto custa?
O mesmo que no site: 60 créditos a cada 1.000 caracteres, com mínimo de 100 por requisição. Sem mensalidade e sem custo por chamada. Se um áudio falhar, os créditos são devolvidos.
Em que formato sai o áudio?
MP3.
Posso pedir vários vídeos de uma vez?
Sim, com POST /videos/batches: um só mínimo para todos, e se juntos passam dele, nenhum o paga. Começam em ordem e, se houver espaço, vários ao mesmo tempo; os que esperam aparecem como pending e dá para cancelar até começarem.
Posso enviar uma foto pela API?
Sim, com POST /avatars e "consent": true, que confirma que é o seu rosto ou que você tem a permissão dessa pessoa. Também pode enviar pelo site.
Quais avatares posso usar?
Os seus e os avatares da biblioteca que você salvou nos favoritos. GET /avatars lista todos, com as cenas.

Escreva o seu texto e ouça com uma voz real

A API gasta créditos de um pacote (60 a cada 1.000 caracteres). Pacotes a partir de US$ 6,99, sem assinatura.