Vioxfy — Documentação da API v1

Fluxo completo

Da chave ao áudio em 3 passos.

Direto, sem fila e sem polling. Você chama, a gente devolve o arquivo na mesma resposta.

Passo 1

Sua chave

Pegue em /app › API. Formato sk_live_…

Passo 2

POST /v1/tts

Manda text + voice. Volta o MP3 na hora.

Passo 3

Legenda SRT

GET /v1/subtitles com o X-Job-Id do header.

Quickstart

Seu primeiro áudio em 60 segundos.

1

Pegue a chave

No app, botão API no topo. Copie o sk_live_…

2

Envie o texto

POST /v1/tts com text + voice. Já devolve o MP3.

3

Pegue a legenda

GET /v1/subtitles/{job} com o X-Job-Id do header.

Cole no terminal

# 1. Gera o áudio — já baixa o MP3 e os headers (X-Job-Id / X-Subtitles-Url)
curl -X POST "__BASE__/v1/tts" \
  -H "x-api-key: sk_live_SUA_CHAVE" \
  -F "text=Olá! Primeiro teste da API do Vioxfy." \
  -F "voice=vz_ID_DA_VOZ" \
  --output audio.mp3 --dump-header headers.txt

# 2. Baixa a legenda .srt (use o X-Job-Id que veio no passo 1)
curl "__BASE__/v1/subtitles/JOB_ID?type=legenda&val=5" \
  -H "x-api-key: sk_live_SUA_CHAVE" --output legenda.srt

Autenticação

Uma chave, dois jeitos.

Toda requisição leva a sua chave de API. Você a encontra no app em API, no formato sk_live_…. Mande em um destes headers:

Authorization: Bearer sk_live_SUA_CHAVE
# ou
x-api-key: sk_live_SUA_CHAVE

Guarde sua chave. Ela é vinculada à sua conta e ao seu plano — quem tiver a chave gera áudio no seu limite. Nunca exponha no front-end de um site público.

Playground

Teste de verdade, aqui mesmo.

Sem sair da página e sem escrever código. Se você estiver logado, sua chave já vem preenchida — é só clicar em enviar e ouvir o resultado.

Sua chave

GET Vozes

POST Gerar áudio

POST Transcrever

GET Uso

Lista as vozes da sua conta. Filtre por gênero, idioma ou busca.

Busca (opcional)

Gênero

Idioma (código, opcional)

Rode fora da ferramenta

Teste na sua máquina.

Copie, cole a sua chave e rode no terminal, no seu código ou no n8n. É o fluxo completo: escolher a voz → gerar o MP3 → baixar a legenda. Fora do app, com a sua chave.

# 1) Gera o áudio — já baixa o MP3 e guarda os headers (X-Job-Id)
curl -X POST "__BASE__/v1/tts" \
  -H "x-api-key: sk_live_SUA_CHAVE" \
  -F "text=Olá! Testando a API do Vioxfy fora do app." \
  -F "voice=vz_ID_DA_VOZ" \
  -o audio.mp3 -D headers.txt

# 2) Pega o job id do header e baixa a legenda .srt
JOB=$(grep -i x-job-id headers.txt | tr -d '\r' | awk '{print $2}')
curl "__BASE__/v1/subtitles/$JOB?type=legenda&val=5" \
  -H "x-api-key: sk_live_SUA_CHAVE" -o legenda.srt

echo "pronto: audio.mp3 + legenda.srt"

# pip install requests
import requests

BASE = "__BASE__/v1"
KEY  = "sk_live_SUA_CHAVE"
h = {"x-api-key": KEY}

# 1) escolhe uma voz (a 1ª da sua conta)
voices = requests.get(f"{BASE}/voices", headers=h).json()["voices"]
voice = voices[0]["id"]

# 2) gera o áudio — síncrono: a resposta JÁ é o MP3
r = requests.post(f"{BASE}/tts", headers=h,
                  data={"text": "Olá! Testando a API do Vioxfy.", "voice": voice})
open("audio.mp3", "wb").write(r.content)
job = r.headers["X-Job-Id"]

# 3) baixa a legenda .srt do mesmo job
srt = requests.get(f"{BASE}/subtitles/{job}", headers=h,
                   params={"type": "legenda", "val": 5}).text
open("legenda.srt", "w", encoding="utf-8").write(srt)
print("pronto: audio.mp3 + legenda.srt")

// Node 18+ (fetch e FormData nativos). Salve como teste.mjs e rode: node teste.mjs
import fs from "node:fs";

const BASE = "__BASE__/v1";
const KEY  = "sk_live_SUA_CHAVE";
const h = { "x-api-key": KEY };

// 1) escolhe uma voz
const { voices } = await (await fetch(`${BASE}/voices`, { headers: h })).json();
const voice = voices[0].id;

// 2) gera o áudio (a resposta é o MP3)
const fd = new FormData();
fd.append("text", "Olá! Testando a API do Vioxfy.");
fd.append("voice", voice);
const res = await fetch(`${BASE}/tts`, { method: "POST", headers: h, body: fd });
fs.writeFileSync("audio.mp3", Buffer.from(await res.arrayBuffer()));
const job = res.headers.get("X-Job-Id");

// 3) baixa a legenda
const srt = await (await fetch(`${BASE}/subtitles/${job}?type=legenda&val=5`, { headers: h })).text();
fs.writeFileSync("legenda.srt", srt);
console.log("pronto: audio.mp3 + legenda.srt");

No n8n, o jeito mais rápido é importar o cURL direto num nó HTTP Request:

Adicione um nó HTTP Request e clique em Import cURL.
Cole o comando da aba cURL (troque sk_live_SUA_CHAVE e a voice). O n8n preenche método, URL, header e o corpo sozinho.
Em Response → Response Format, escolha File (o corpo é o MP3). O header X-Job-Id vem em Response Headers.
Ligue um segundo nó HTTP Request em GET __BASE__/v1/subtitles/<X-Job-Id>?type=legenda&val=5 (use a expressão do n8n pra pegar o x-job-id do nó anterior) com o mesmo header, pra baixar a legenda.

Dica: guarde a chave em Credentials → Header Auth (nome x-api-key) e reaproveite em todos os nós, sem deixar a chave exposta no fluxo.

A mesma chave do Playground vale aqui. Rodou na sua máquina? Então está pronto pra produção — é o mesmo endpoint.

Endpoints

Referência completa.

Todos os endpoints são /v1/* e pedem a sua chave. Respostas de erro vêm como { "error": "…" }.

GET/v1/voices

Retorna as vozes disponíveis pra sua conta — inclui as suas vozes clonadas.

Query params (opcionais)

Param	Descrição
`language`	Código do idioma (ex.: `pt`, `en`, `fr`).
`gender`	`F` (feminino) ou `M` (masculino).
`search`	Filtra por nome/descrição.

Exemplo

curl "__BASE__/v1/voices?gender=M&language=pt" \
  -H "x-api-key: sk_live_SUA_CHAVE"

Resposta

{
  "voices": [
    {
      "id": "vz_a1b2c3",
      "name": "Adriano – Grave BR",
      "gender": "M",
      "language": "pt",
      "has_preview": true,
      "is_clone": false
    }
  ]
}

GET/v1/voices/{voice_id}/preview

Devolve um audio/mpeg curto com a prévia da voz. Aceita ?lang= pra escolher a prévia num idioma específico.

curl "__BASE__/v1/voices/vz_a1b2c3/preview" \
  -H "x-api-key: sk_live_SUA_CHAVE" --output previa.mp3

POST/v1/tts

Gera o áudio e devolve o MP3 direto — não há fila. O corpo é multipart/form-data (ou x-www-form-urlencoded).

Campos (form)

Campo		Descrição
`text`	obrig.	Texto pra narração. O limite de caracteres depende do seu plano.
`voice`	obrig.	ID da voz (obtido em `/v1/voices`).
`rate`	opc.	Velocidade da fala, de `0.5` a `2.0` (padrão `1.0`).

A resposta é o arquivo MP3. O header X-Job-Id traz o id do áudio — use-o em /v1/subtitles pra baixar as legendas.

Exemplo

curl -X POST "__BASE__/v1/tts" \
  -H "x-api-key: sk_live_SUA_CHAVE" \
  -F "text=Olá, este é um teste." \
  -F "voice=vz_a1b2c3" \
  -F "rate=1.0" \
  --output audio.mp3 --dump-header -

Headers da resposta

X-Job-Id: 9f8e7d6c5b4a…
X-Subtitles-Url: /v1/subtitles/9f8e7d6c5b4a…

GET/v1/subtitles/{job_id}

Gera a legenda .srt do áudio, no formato que você escolher. Use o job_id do header X-Job-Id do /v1/tts.

Query params

Param		Descrição
`type`	opc.	`legenda` (padrão), `palavra` (nº fixo de palavras) ou `tempo` (blocos por segundos).
`val`	opc.	Nº de palavras (`legenda`/`palavra`) ou segundos por bloco (`tempo`). Padrão `5`.
`fmt`	opc.	Caixa do texto: `upper`, `lower` ou `cap` (1ª maiúscula).

curl "__BASE__/v1/subtitles/9f8e7d6c?type=tempo&val=3" \
  -H "x-api-key: sk_live_SUA_CHAVE" --output legenda.srt

POST/v1/transcribe

Envie um arquivo de áudio/vídeo (multipart/form-data) e receba o texto + tempos por palavra.

Campos (form)

Campo		Descrição
`file`	obrig.	Arquivo de áudio ou vídeo.
`language_code`	opc.	Idioma (ex.: `pt-BR`). Vazio = detecta.
`output`	opc.	`json` (padrão), `text` (texto puro) ou `srt`.
`srt_words`	opc.	Palavras por linha quando `output=srt` (padrão 8).

curl -X POST "__BASE__/v1/transcribe" \
  -H "x-api-key: sk_live_SUA_CHAVE" \
  -F "file=@narracao.mp3" \
  -F "language_code=pt-BR" \
  -F "output=json"

Resposta (output=json)

{
  "ok": true,
  "job": "tr_1a2b3c…",
  "language": "pt-BR",
  "text": "Texto transcrito completo…",
  "duration_ms": 12840,
  "n_palavras": 34,
  "segments": [ { "text": "Texto", "start": 0.0, "end": 0.42 } ]
}

Guarde o job: dá pra reformatar a mesma transcrição depois (por tempo, por palavra, texto puro) sem gastar outro crédito — veja abaixo.

GET/v1/transcribe/{job}

Reformata uma transcrição já feita, sem re-transcrever — não gasta crédito.

Query params

Param		Descrição
`type`	opc.	`text` (padrão), `palavra`, `tempo`, `legenda` ou `json`.
`val`	opc.	Palavras/segundos por bloco (conforme o type).
`fmt`	opc.	`upper`, `lower` ou `cap`.

curl "__BASE__/v1/transcribe/tr_1a2b3c?type=tempo&val=4" \
  -H "x-api-key: sk_live_SUA_CHAVE"

POST/v1/clone

Cria uma voz clonada a partir de uma amostra sua. Disponível em planos com clonagem. A voz criada fica privada na sua conta e passa a aparecer em /v1/voices.

Campos (form)

Campo		Descrição
`file`	obrig.	Amostra de áudio da voz.
`prompt_text`	obrig.	O texto exato falado na amostra.
`name`	opc.	Nome da voz (padrão "Minha voz").
`language_code`	opc.	Idioma da amostra (padrão `pt-BR`).

curl -X POST "__BASE__/v1/clone" \
  -H "x-api-key: sk_live_SUA_CHAVE" \
  -F "file=@amostra.wav" \
  -F "prompt_text=texto exato que eu falei na amostra" \
  -F "name=Minha voz"

Resposta

{ "ok": true, "voice": { "id": "vz_…", "name": "Minha voz", "is_clone": true } }

GET/v1/usage

Retorna seu uso do dia e os limites do plano — bom pra mostrar saldo no seu próprio painel.

curl "__BASE__/v1/usage" -H "x-api-key: sk_live_SUA_CHAVE"

Resposta

{
  "plan": "pro",
  "plan_nome": "Pro",
  "usado_hoje": 5,
  "limite_dia": 100,
  "restante": 95,
  "max_chars": 150000,
  "clone": true,
  "por_tipo": { "tts": 3, "transcribe": 1, "clone": 1 },
  "reset_ms": 1783652400000
}

Referência

Códigos de erro.

Erros vêm como JSON: { "error": "mensagem" }. Trate pelo status HTTP.

Código	Significado
`400`	Requisição inválida (texto vazio, voz não encontrada, parâmetro inválido).
`401`	Chave de API ausente ou inválida.
`403`	Recurso não incluído no plano (ex.: clonagem).
`404`	Áudio, transcrição ou voz não encontrado (áudios expiram em ~48h).
`413`	Texto excede o limite de caracteres do plano.
`422`	O provedor de voz bloqueou uma palavra do texto — reescreva o trecho.
`429`	Limite diário de gerações, ou de requisições por minuto, atingido.
`502 / 503`	Falha temporária ao gerar/transcrever, ou manutenção. Tente de novo em instantes.

Referência

Limites & regras.

Gerações por dia

Conforme o seu plano — compartilhado entre áudio, transcrição e clonagem.

Caracteres por áudio

Conforme o plano, por geração (não acumula). No Pro, até 150 mil por áudio.

Valores em tempo real

Consulte sempre por GET /v1/usage — nunca chumbe no código.

Os áudios são temporários: baixe o MP3 e a legenda logo após gerar. Depois de ~48h o job_id pode retornar 404.

Sua voz em produção com um POST.

Da chave ao áudio em 3 passos.

Seu primeiro áudio em 60 segundos.

Uma chave, dois jeitos.

Teste de verdade, aqui mesmo.

Teste na sua máquina.

Referência completa.

Códigos de erro.

Limites & regras.

Pegue sua chave e gere o primeiro áudio.