GUIA

API de texto para fala auto-hospedada no Docker

Uma API de texto para fala no seu próprio servidor transforma texto em áudio para qualquer programa que consiga enviar uma requisição HTTP: um site, um bot, o backend de um jogo ou um script em qualquer linguagem. O texto não sai da sua máquina e não há cobrança por caractere.

Este guia mostra como rodar o motor SuperClonica, baseado no modelo aberto Supertonic 3, como servidor HTTP no Docker: a inicialização em CPU ou GPU NVIDIA, as requisições com vozes embutidas e personalizadas, e a preparação para uso real. A imagem e o motor são nossos, por isso dizemos quando o assunto somos nós.

Ver vozes para a sua API Outras formas de instalar o motor

Por que rodar a síntese de voz por conta própria

Com APIs de voz na nuvem é fácil começar, mas cada requisição envia seu texto ao provedor e é cobrada por caractere. Uma API auto-hospedada troca isso por um servidor que você administra.

  • Privacidade: textos e áudio ficam no seu hardware, o que importa para documentos internos, mensagens e dados de usuários.
  • Custo: depois do hardware, a fala é gratuita; textos longos e grandes volumes não aumentam a conta.
  • Qualquer cliente: um único endpoint HTTP atende igualmente Python, JavaScript, Go, PHP, C# ou um script de shell.
  • Offline: depois que o modelo é baixado, o servidor não precisa de internet.

Iniciar o servidor

Em qualquer CPU: docker run -d --name tts -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cpu. Em uma GPU NVIDIA, instale o NVIDIA Container Toolkit e use docker run -d --name tts --gpus all -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cuda; a imagem traz CUDA e cuDNN, e o host precisa apenas do driver.

A primeira inicialização baixa o modelo Supertonic 3, com cerca de 385 MB, para o volume superclonica-models; as seguintes o reutilizam. O servidor está pronto quando GET http://localhost:8000/health responde com status, versão e o dispositivo em uso. A imagem tem sua própria verificação de saúde, então o docker ps mostra quando ela está pronta.

Enviar uma requisição

POST /synthesize recebe JSON e responde com um arquivo WAV mono de 16 bits: curl -X POST http://localhost:8000/synthesize -H "Content-Type: application/json" -d '{"text": "Olá do meu próprio servidor!", "voice": "F1", "lang": "pt"}' -o ola.wav. Os cabeçalhos X-Sample-Rate e X-Duration-Seconds descrevem o áudio.

Os campos são text, voice, lang, seed e normalize. voice é uma das dez vozes embutidas, de M1 a M5 e de F1 a F5, ou uma voz personalizada; lang é o idioma do texto, um dos 31 idiomas do modelo (o chinês não está entre eles). Uma semente fixa gera o mesmo áudio para o mesmo texto, e normalize iguala o volume. GET /voices lista as vozes embutidas e os idiomas, e /docs mostra a documentação interativa da API.

Usar vozes personalizadas

Uma voz do Supertonic 3 é um arquivo JSON de cerca de 0,3 MB. Há vozes gratuitas com amostras de áudio no repositório superclonica/supertonic-voices do GitHub, e o catálogo da SuperClonica tem mais de 170, cada uma com demo online gratuita.

A voz vai na requisição como o próprio objeto JSON, no campo voice, então o servidor não guarda arquivos de voz. Como o objeto é grande, monte a requisição em um arquivo e envie com curl -d @request.json, ou no código: carregue a voz com json.load em Python ou JSON.parse em JavaScript e envie junto com o texto. O corpo de uma requisição pode ter até 2 MB.

Configurações

O servidor lê as configurações de variáveis de ambiente, passadas com -e no docker run ou em um arquivo Compose.

  • SUPERCLONICA_API_KEY: quando definida, /synthesize e /voices exigem o cabeçalho Authorization: Bearer seguido da chave.
  • SUPERCLONICA_LANES: cópias do modelo, de 1 a 8 (padrão 1); cada uma atende uma requisição por vez e precisa da própria memória.
  • SUPERCLONICA_DEVICE: auto, cuda ou cpu (padrão auto: a GPU, se houver).
  • SUPERCLONICA_THREADS: threads da CPU (padrão um por núcleo físico).
  • SUPERCLONICA_MAX_TEXT: o texto mais longo em caracteres (padrão 5000).

Antes de colocar em produção

Alguns hábitos mantêm uma API de voz auto-hospedada rápida e segura.

  • Mantenha o volume /models, para que reinicializações não baixem o modelo de novo, e inicie o contêiner com --restart unless-stopped.
  • Não exponha a porta 8000 na internet do jeito que está: defina uma chave de API e coloque o servidor atrás de um proxy reverso com HTTPS, ou mantenha-o em uma rede privada.
  • Divida você mesmo textos longos em parágrafos se precisar de progresso ou streaming; o motor já fala um texto longo em trechos naturais de até 160 caracteres.
  • Guarde em cache o áudio de textos que se repetem, como frases da interface: o mesmo texto, voz e semente sempre geram o mesmo arquivo.
  • Meça no seu hardware: nos nossos testes, uma frase curta levou 0,12 s numa RTX 5070 Ti e 0,43 s em quatro threads de um Ryzen 7 5800X.

Licenças

O motor SuperClonica e a imagem são distribuídos sob a Apache License 2.0. O modelo Supertonic 3 está sob OpenRAIL-M, uma licença livre de royalties com uma lista de usos proibidos em vez de uma cláusula não comercial: não use a fala para se passar por alguém sem consentimento, para enganar ou para assediar, e informe que o áudio é gerado por máquina quando isso importar.