v1 — estável

API Aivoxs

Integre TTS, clonagem de voz e diálogos multi-falante no seu produto. REST simples, Bearer Token e jobs assíncronos.

Introdução

A API Aivoxs oferece acesso programático aos motores de voz da plataforma. Toda chamada é autenticada com um Bearer Token pessoal, criado em Painel → Minha API. Os endpoints de geração retornam jobs assíncronos que devem ser consultados em GET /v1/jobs/:id até completed ou failed.

Base URL

Produção (recomendada — quando DNS estiver ativo):

text

https://api.aivoxs.pro/v1

Endpoint estável atual (sempre disponível):

text

https://aivoxs.pro/api/public/v1

A base é configurada via VITE_PUBLIC_API_URL. Clientes devem usar a variável PUBLIC_API_URL em seu próprio ambiente.

Autenticação

Toda requisição (exceto /health e /openapi.json) exige o header:

http

Authorization: Bearer aiv_live_SEU_TOKEN

Exemplo prático:

bash

curl "https://api.aivoxs.pro/v1/credits" \
  -H "Authorization: Bearer aiv_live_SEU_TOKEN"

O token pertence ao usuário dono da conta.
Só funciona se a conta tiver plano pago ativo + flag api_enabled.
Trial gratuito não pode criar token.
Tokens revogados param de funcionar imediatamente.
Nunca exponha o token em frontend público.

Tokens de API

Gerencie tokens em /dashboard/api. O valor do token aparece uma única vez no momento da criação — o backend armazena apenas o SHA-256. Guarde em um secret manager.

Cada token pode ter scopes específicos. Os scopes existentes são:

text

credits:read
voices:read
tts:create
dialogue:create
voice_clone:create
jobs:read

Planos e permissões

API disponível apenas para contas com plano pago ativo. Erro esperado:

json

{
  "error": {
    "code": "plan_required",
    "message": "API access requires an active paid plan."
  }
}

Créditos

Cada chamada que processa áudio/texto consome créditos pagos da carteira do usuário dono do token. O custo final é o credit_cost retornado pela engine. Créditos de trial gratuito não são consumidos pela API — chamadas sem saldo não-trial retornam 402 INSUFFICIENT_CREDITS.

Idempotência

Planejado

O header Idempotency-Key está planejado para a v1.1. Quando disponível, retentativas de POST com a mesma chave retornarão o mesmo job, evitando cobrança duplicada. Conflitos de payload retornam 409 idempotency_conflict.

bash

curl -X POST "https://api.aivoxs.pro/v1/text-to-speech" \
  -H "Authorization: Bearer aiv_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123" \
  -d '{"text":"Olá","voice_id":"voice_public_xxx"}'

Rate limits

Limite atual: 60 requisições por minuto por token. Headers de resposta:

text

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After (somente em 429)

json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Muitas requisições. Tente novamente em instantes."
  }
}

Erros

Todos os erros seguem o formato:

json

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token inválido ou expirado."
  }
}

HTTP	Código	Significado
400	BAD_REQUEST	Payload malformado
401	MISSING_TOKEN	Header Authorization ausente
401	INVALID_TOKEN	Token inválido, expirado ou revogado
402	INSUFFICIENT_CREDITS	Sem saldo pago elegível
403	FORBIDDEN_SCOPE	Token sem o scope exigido
404	NOT_FOUND	Endpoint ou recurso inexistente
429	RATE_LIMITED	Limite por minuto excedido
500	INTERNAL	Erro inesperado no servidor

Vozes

Vozes públicas estão no catálogo global. Vozes privadas (clonadas) só aparecem para o dono do token. voice_id privado de outro usuário nunca funciona.

Jobs

Endpoints de geração retornam 202 Accepted com um job:

json

{ "job": { "id": "uuid", "type": "tts", "status": "queued" } }

Estados possíveis:

text

queued → processing → completed
                      ↓
                    failed

Use polling com backoff em GET /v1/jobs/:id. Recomendado: 2s, depois 5s, depois 10s. Evite loops agressivos.

GET/v1/health

Healthcheck

Sem autenticação. Use para monitoramento.

bash

curl "https://api.aivoxs.pro/v1/health"

json

{ "status": "ok", "version": "v1", "time": "2026-01-01T00:00:00Z" }

GET/v1/credits

scope: credits:read

Consultar créditos

Retorna saldo elegível para uso via API (sem trial).

bash

curl "https://api.aivoxs.pro/v1/credits" \
  -H "Authorization: Bearer aiv_live_SEU_TOKEN"

json

{
  "balance": 120000,
  "reserved": 0,
  "available": 120000,
  "plan": "pro",
  "period": { "start": "...", "end": "..." }
}

GET/v1/voices

scope: voices:read

Listar vozes

Filtros opcionais: language, provider, limit (máx 200).

bash

curl "https://api.aivoxs.pro/v1/voices?language=pt-BR&limit=20" \
  -H "Authorization: Bearer aiv_live_SEU_TOKEN"

json

{
  "voices": [
    {
      "id": "voice_public_xxx",
      "name": "Voz pública",
      "provider": "elevenlabs",
      "language": "pt-BR"
    }
  ],
  "count": 1
}

POST/v1/text-to-speech

scope: tts:create

Texto para voz

Gera áudio TTS. Retorna job assíncrono.

bash

curl -X POST "https://api.aivoxs.pro/v1/text-to-speech" \
  -H "Authorization: Bearer aiv_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Olá, mundo!",
    "voice_id": "voice_public_xxx",
    "language": "pt-BR"
  }'

json

{ "job": { "id": "uuid", "type": "tts", "status": "queued" } }

POST/v1/voice-clones

scope: voice_clone:create

Clonagem de voz

Amostra de áudio (mp3/wav/m4a, até 10MB) + nome. A voz fica disponível apenas para o dono do token.

bash

curl -X POST "https://api.aivoxs.pro/v1/voice-clones" \
  -H "Authorization: Bearer aiv_live_SEU_TOKEN" \
  -F "audio_file=@sample.wav" \
  -F "name=Minha Voz" \
  -F "language=pt-BR"

json

{ "job": { "id": "uuid", "type": "voice_clone", "status": "queued" } }

Quando o job concluir, result.voice_id traz o ID a usar em chamadas futuras de /text-to-speech ou /dialogues.

POST/v1/dialogues

scope: dialogue:create

Diálogo multi-falante

Roteiro com várias vozes; suporta tags inline ([speed_slow], [long_pause], [amusement], etc).

bash

curl -X POST "https://api.aivoxs.pro/v1/dialogues" \
  -H "Authorization: Bearer aiv_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": [
      { "voice_id": "voice_a", "text": "Oi [amusement] tudo bem?" },
      { "voice_id": "voice_b", "text": "Tudo [long_pause] e você?" }
    ],
    "with_transcript": true
  }'

json

{ "job": { "id": "uuid", "type": "dialogue", "status": "queued" } }

GET/v1/jobs/:id

scope: jobs:read

Consultar job

Reconcilia status com o pipeline interno. Só vê jobs do próprio token.

bash

curl "https://api.aivoxs.pro/v1/jobs/<id>" \
  -H "Authorization: Bearer aiv_live_SEU_TOKEN"

json

{
  "job": {
    "id": "uuid",
    "type": "tts",
    "status": "completed",
    "credits_used": 1234,
    "result": { "audio_url": "https://.../file.mp3" }
  }
}

Arquivos e resultados

Planejado

O endpoint GET /v1/files/:file_id está planejado. Hoje, URLs de resultado vêm diretamente no campo result.audio_url do job concluído. As URLs são temporárias e nunca expõem caminhos do provedor.

Boas práticas

Nunca exponha o token no frontend.
Use variáveis de ambiente (AIVOXS_API_TOKEN).
Implemente retry com backoff progressivo (2s, 5s, 10s).
Trate 401, 402, 403 e 429 explicitamente.
Monitore X-RateLimit-Remaining.
Revogue tokens não utilizados.
Use tags inline (ex.: [amusement], [long_pause]) só em /text-to-speech e /dialogues.

Exemplos completos

Node.js

javascript

const API_TOKEN = process.env.AIVOXS_API_TOKEN;
const BASE = "https://api.aivoxs.pro/v1";

async function createTTS(text, voiceId) {
  const r = await fetch(`${BASE}/text-to-speech`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text, voice_id: voiceId }),
  });
  const data = await r.json();
  if (!r.ok) throw new Error(data.error?.message ?? "API error");
  return data.job;
}

async function waitJob(id) {
  for (let i = 0; i < 60; i++) {
    const r = await fetch(`${BASE}/jobs/${id}`, {
      headers: { Authorization: `Bearer ${API_TOKEN}` },
    });
    const { job } = await r.json();
    if (job.status === "completed" || job.status === "failed") return job;
    await new Promise(res => setTimeout(res, Math.min(2000 + i * 500, 10000)));
  }
  throw new Error("timeout");
}

Python

python

import os, time, requests

API = "https://api.aivoxs.pro/v1"
TOKEN = os.environ["AIVOXS_API_TOKEN"]
H = {"Authorization": f"Bearer {TOKEN}"}

def create_tts(text, voice_id):
    r = requests.post(f"{API}/text-to-speech", headers={**H, "Content-Type": "application/json"},
                      json={"text": text, "voice_id": voice_id})
    r.raise_for_status()
    return r.json()["job"]

def wait_job(job_id):
    delay = 2
    for _ in range(60):
        r = requests.get(f"{API}/jobs/{job_id}", headers=H)
        job = r.json()["job"]
        if job["status"] in ("completed", "failed"):
            return job
        time.sleep(delay)
        delay = min(delay + 1, 10)

PHP

php

<?php
$token = getenv("AIVOXS_API_TOKEN");
$ch = curl_init("https://api.aivoxs.pro/v1/text-to-speech");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $token",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "text" => "Olá", "voice_id" => "voice_public_xxx"
  ]),
]);
$resp = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($resp);

Segurança

Token nunca é retornado em texto plano após criação.
Logs de uso não armazenam payloads; IP e User-Agent ficam como hash.
IDs internos do provedor nunca são expostos.
Use HTTPS sempre — chamadas HTTP são rejeitadas.

Changelog

v1.0.0Atual

Autenticação Bearer + scopes
Endpoints: credits, voices, jobs
Geração: TTS, dialogues, voice-clones
Rate limit por token (60/min)
Bloqueio de saldo trial

Markdown para IAs

Documento condensado para você colar em qualquer LLM e gerar integração automática:

Baixar Markdown

text

Você é uma IA desenvolvedora. Crie uma integração segura com a API Aivoxs.

Base URL: https://api.aivoxs.pro/v1
Auth: Authorization: Bearer AIVOXS_API_TOKEN

Regras obrigatórias:
- Nunca exponha o token no frontend; use variável de ambiente em backend.
- Use Idempotency-Key em todas as chamadas POST.
- A API retorna jobs assíncronos. Após POST, consulte GET /v1/jobs/:id até status completed ou failed.
- Trate erros 401, 402, 403, 409, 422 e 429 com mensagens claras.
- Endpoints ativos na v1: /credits, /voices, /text-to-speech, /voice-clones, /dialogues, /jobs/:id, /health.
- Não invente endpoints além dos documentados (transcrição, voice-changer e dubbing não estão disponíveis).
- Não logue tokens nem áudios.

Implemente:
1. Configurar token via env (AIVOXS_API_TOKEN).
2. GET /v1/credits — checar saldo antes de chamadas pagas.
3. GET /v1/voices — listar vozes disponíveis.
4. POST /v1/text-to-speech — criar job de TTS.
5. Polling em GET /v1/jobs/:id com backoff (2s → 5s → 10s).
6. Baixar/exibir result.audio_url do job completado.
7. Tratar erros e exibir códigos.

OpenAPI 3.1

Schema completo em /api/public/v1/openapi.json. Útil para gerar clientes em qualquer linguagem (openapi-generator, Stainless, etc).