API v1.0

API do Vioxfy

Gere áudio com vozes naturais, transcreva e clone vozes por uma API REST simples. A geração é síncrona: um único POST /v1/tts já devolve o MP3 pronto.

__BASE__/v1

Fluxo completo

Da sua chave ao áudio pronto — a geração é direta, sem fila.

Sua chave

→

Listar vozes

GET

→

Gerar áudio

POST

→

Legendas SRT

GET

Quickstart

Seu primeiro áudio em menos de 60 segundos.

Pegue sua chave

No app, botão API no topo. O formato é sk_live_…

Envie o texto

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

Pegue as legendas

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

Teste agora

# 1. Gera o audio (ja devolve o MP3 + header 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 as legendas .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"

Autenticação

Toda requisição precisa da sua chave de API. Você a encontra no app em Configurações › API. O formato é sk_live_.... Envie de uma das duas formas:

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

Sua chave é vinculada à sua conta e ao seu plano. Não compartilhe — quem tiver a chave gera áudio no seu limite.

Ambiente de testes

Teste a API aqui mesmo, sem sair da página. Se você estiver logado, sua chave já vem preenchida.

Sua chave

Listar vozes

Gerar áudio

Transcrever

Uso

Busca (opcional)

Gênero

Idioma (código, opcional)

Listar vozes

GET/v1/voices

Retorna as vozes disponíveis para a 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": "Benoit – Swiss Finance",
      "gender": "M",
      "language": "fr",
      "has_preview": true,
      "is_clone": false
    }
  ]
}

Prévia de voz

GET/v1/voices/{voice_id}/preview

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

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

Gerar áudio

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 para 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 para 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 -

Resposta

Corpo binário audio/mpeg + headers:

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

Baixar legenda

GET/v1/subtitles/{job_id}

Gera a legenda .srt do áudio gerado, no formato que você escolher. Use o job_id devolvido no 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 (types `legenda`/`palavra`) ou segundos por bloco (type `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

Transcrever

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.

Reformatar transcrição

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"

Clonar voz

POST/v1/clone

Cria uma voz clonada a partir de uma amostra sua. Disponível apenas em planos com clonagem. A voz criada fica privada na sua conta e aparece 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 } }

Uso / limites

GET/v1/usage

Retorna seu uso do dia e os limites do plano.

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": 70000,
  "clone": true,
  "por_tipo": { "tts": 3, "transcribe": 1, "clone": 1 },
  "reset_ms": 1783652400000
}

Códigos de erro

Erros vêm como JSON: { "error": "mensagem" }.

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/voz não encontrado.
`413`	Texto excede o limite de caracteres do plano.
`422`	O provedor de voz bloqueou uma palavra do texto.
`429`	Limite diário de gerações atingido.
`502`	Falha ao gerar/transcrever no provedor.

Limites

Gerações por dia: conforme o seu plano (compartilhado entre áudio, transcrição e clonagem).
Caracteres por áudio: conforme o seu plano (por geração, não acumulado).
Consulte os valores atuais em tempo real por GET /v1/usage.