API Reference

A API do Hidraa TTS permite converter texto em fala com qualidade profissional diretamente nas suas aplicações. 1 token = 1 caractere.

https://app.hidraa.com.br

Onde encontro minha API Key?
Acesse app.hidraa.com.br → Perfil → Chave de API. Copie e use no header X-API-Key.

Autenticação

Todos os endpoints protegidos exigem autenticação via API Key. Envie pelo header X-API-Key ou como Bearer no header Authorization.

Opção 1 — Header dedicado (recomendado)

        HTTP
X-API-Key: hta_sua_chave_aqui
      

Opção 2 — Bearer Authorization

        HTTP
Authorization: Bearer hta_sua_chave_aqui
      

Sua API Key tem acesso completo à sua conta. Nunca a exponha em código client-side público ou em repositórios git.

Erros

A API retorna erros em JSON com a chave error.

Status	Significado
400	Requisição inválida — verifique os parâmetros
401	API Key ausente, inválida ou expirada
402	Tokens insuficientes — compre mais tokens
404	Recurso não encontrado
429	Rate limit atingido — aguarde antes de tentar novamente
500	Erro interno — tente novamente em instantes

        JSON
{
  "error": "Tokens insuficientes",
  "required": 1500,
  "available": 800
}
      

Rate Limits

Endpoint	Limite	Janela
`/api/tts/generate`	10 requisições	1 minuto por usuário
Demais endpoints	200 requisições	15 minutos por IP

Síntese de Voz

POST /api/tts/generate

Converte texto em áudio WAV. Debita tokens da sua conta (mensais primeiro, depois comprados). Corpo da requisição deve ser multipart/form-data.

Parâmetros

Campo	Tipo	Obrig.	Descrição
text	string	sim	Texto a ser convertido. Máx. 5.000 caracteres.
voice	string	não	ID da voz. Default: `female_default`. Ver GET /tts/voices.
engine	string	não	`omnivoice` — OmniVoice AI (646 idiomas). Único engine suportado.
language	string	não	Código do idioma. Ex: `pt`, `en`, `es`. Default: `pt`.
title	string	não	Título para identificar no histórico. Máx. 200 chars.
refAudio	file	não	Áudio de referência para clonagem de voz (somente OmniVoice). MP3/WAV/M4A, máx. 10MB.

Resposta 200

        JSON
{
  "id": "664a1b2c3d4e5f6a7b8c9d0e",
  "audioUrl": "https://s3.us-east-1.idrivee2.com/hidraa-tts/...",
  "audioDuration": 12,
  "audioSize": 380416,
  "tokensConsumed": 245,
  "balance": {
    "monthly": { "limit": 5000, "used": 245, "remaining": 4755 },
    "purchased": { "total": 50000, "used": 0, "remaining": 50000 },
    "total": 54755
  }
}
      

⏱ audioUrl é uma URL assinada válida por 1 hora. Use GET /tts/:id/url para renová-la.

GET /api/tts/voices

Lista todos os modelos de voz disponíveis. Não requer autenticação.

        JSON
{
  "voices": [
    {
      "id": "female_default",
      "name": "Roberta Sales",
      "gender": "female",
      "lang": "pt",
      "engine": "omnivoice",
      "description": "Voz feminina padrão — clara e profissional",
      "tags": ["pt-BR", "profissional", "padrão"]
    },
    {
      "id": "male_formal",
      "name": "Carlos",
      "gender": "male",
      "lang": "pt",
      "engine": "omnivoice",
      "description": "Voz masculina formal — ideal para corporativo",
      "tags": ["pt-BR", "formal", "corporativo"]
    }
  ]
}
      

GET /api/tts/languages

Lista os idiomas suportados para síntese. Não requer autenticação.

        JSON
{
  "languages": [
    { "code": "pt", "name": "Português (BR)", "flag": "🇧🇷" },
    { "code": "en", "name": "English (US)",   "flag": "🇺🇸" },
    { "code": "es", "name": "Español",         "flag": "🇪🇸" }
  ]
}
      

GET /api/tts/:id/url

Gera uma nova URL assinada para um áudio já gerado. Útil quando a URL anterior expirou. Requer autenticação.

        JSON
{
  "audioUrl": "https://s3.us-east-1.idrivee2.com/hidraa-tts/...",
  "expiresIn": 3600
}
      

Histórico

GET /api/history

Lista os áudios gerados. Requer autenticação. Suporta paginação.

Query	Tipo	Default	Descrição
page	number	1	Número da página
limit	number	20	Itens por página (máx. 100)
favorite	boolean	—	Filtrar favoritos

Tokens

GET /api/tokens/balance

Retorna o saldo de tokens da conta. Requer autenticação.

        JSON
{
  "monthly": {
    "limit": 5000,
    "used": 1200,
    "remaining": 3800
  },
  "purchased": {
    "total": 50000,
    "used": 400,
    "remaining": 49600
  },
  "total": 53400,
  "resetAt": "2026-05-01T00:00:00.000Z"
}
      

Exemplos — cURL

Gerar áudio simples

        bash
curl -X POST https://app.hidraa.com.br/api/tts/generate \
  -H "X-API-Key: hta_sua_chave_aqui" \
  -F "text=Olá, bem-vindo ao Hidraa TTS!" \
  -F "voice=female_default" \
  -F "engine=omnivoice" \
  -F "language=pt"
      

Com efeitos de emoção

        bash
curl -X POST https://app.hidraa.com.br/api/tts/generate \
  -H "X-API-Key: hta_sua_chave_aqui" \
  -F "text=[feliz]Que ótima notícia![/feliz] Bem-vindo ao Hidraa TTS." \
  -F "voice=female_default" \
  -F "engine=omnivoice" \
  -F "language=pt" \
  -F "title=Audio com efeito feliz"
      

Consultar saldo

        bash
curl https://app.hidraa.com.br/api/tokens/balance \
  -H "X-API-Key: hta_sua_chave_aqui"
      

Exemplos — JavaScript

        JavaScript
const API_KEY = 'hta_sua_chave_aqui';
const BASE = 'https://app.hidraa.com.br';

// Gerar áudio
async function generateAudio(text, voice = 'female_default') {
  const fd = new FormData();
  fd.append('text', text);
  fd.append('voice', voice);
  fd.append('engine', 'omnivoice');
  fd.append('language', 'pt');

  const res = await fetch(`${BASE}/api/tts/generate`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY },
    body: fd
  });

  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();

  // data.audioUrl é válido por 1 hora
  return data;
}

// Uso:
generateAudio('Bem-vindo ao Hidraa TTS!').then(result => {
  console.log('Áudio:', result.audioUrl);
  console.log('Tokens usados:', result.tokensConsumed);
});
      

Baixar o áudio como Buffer (Node.js)

        Node.js
const FormData = require('form-data');
const axios    = require('axios');
const fs       = require('fs');

async function tts(text) {
  const fd = new FormData();
  fd.append('text', text);
  fd.append('voice', 'female_default');
  fd.append('engine', 'omnivoice');

  const { data } = await axios.post(
    'https://app.hidraa.com.br/api/tts/generate',
    fd,
    { headers: { ...fd.getHeaders(), 'X-API-Key': 'hta_sua_chave_aqui' } }
  );

  // Baixar o WAV
  const wav = await axios.get(data.audioUrl, { responseType: 'arraybuffer' });
  fs.writeFileSync('output.wav', Buffer.from(wav.data));
  console.log('Salvo em output.wav!');
}
      

Exemplos — Python

        Python
import requests

API_KEY = "hta_sua_chave_aqui"
BASE    = "https://app.hidraa.com.br"

def generate_audio(text: str, voice: str = "female_default") -> dict:
    response = requests.post(
        f"{BASE}/api/tts/generate",
        headers={"X-API-Key": API_KEY},
        data={
            "text": text,
            "voice": voice,
            "engine": "omnivoice",
            "language": "pt",
        }
    )
    response.raise_for_status()
    return response.json()


def download_audio(audio_url: str, output_path: str = "output.wav"):
    wav = requests.get(audio_url)
    with open(output_path, "wb") as f:
        f.write(wav.content)
    print(f"Salvo em {output_path}")


# Uso:
result = generate_audio("Olá! Bem-vindo ao Hidraa TTS.")
print("Tokens consumidos:", result["tokensConsumed"])
download_audio(result["audioUrl"])
      

Consultar saldo

        Python
res = requests.get(
    f"{BASE}/api/tokens/balance",
    headers={"X-API-Key": API_KEY}
)
balance = res.json()
print(f"Tokens disponíveis: {balance['total']}")
      

Dúvidas? Acesse o Studio ou consulte seu saldo na seção Tokens.