# API de texto para fala auto-hospedada no Docker

Atualizado 2026-10-22

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.

## 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.

## Mais guias

- [Como converter texto em fala offline no seu computador](https://superclonica.com/pt/guides/offline-text-to-speech)
- [Clonagem de voz: como conseguir uma voz parecida com uma gravação](https://superclonica.com/pt/guides/voice-cloning)
- [Os melhores modelos de texto para fala grátis para uso local em 2026](https://superclonica.com/pt/guides/best-free-tts-models)
- [Texto para fala para vídeos, audiolivros, jogos e apps](https://superclonica.com/pt/guides/text-to-speech-for-videos)
- [Vozes do Supertonic 3: onde conseguir vozes próprias e como usá-las](https://superclonica.com/pt/guides/supertonic-3-voices)
- [Texto para fala em Python: offline, grátis e com vozes naturais](https://superclonica.com/pt/guides/python-text-to-speech)

## Texto para fala e comparações

- [Texto para fala que roda no seu próprio computador](https://superclonica.com/pt/text-to-speech)
- [Supertonic vs SuperClonica: o mesmo modelo, mais rápido e limpo](https://superclonica.com/pt/compare/supertonic)
- [Fish Audio e Fish Speech comparados ao SuperClonica](https://superclonica.com/pt/compare/fish-audio)
- [OmniVoice ou SuperClonica: mais idiomas ou mais velocidade](https://superclonica.com/pt/compare/omnivoice)
- [Qwen3-TTS ou SuperClonica para texto para fala local](https://superclonica.com/pt/compare/qwen3-tts)
- [VoxCPM 2 ou SuperClonica: som de estúdio ou velocidade no CPU](https://superclonica.com/pt/compare/voxcpm)
- [F5-TTS ou SuperClonica: clonagem zero-shot ou fala rápida no CPU](https://superclonica.com/pt/compare/f5-tts)
- [Uma alternativa offline ao ElevenLabs](https://superclonica.com/pt/compare/elevenlabs)
- [Kokoro TTS ou SuperClonica: dois modelos pequenos de texto para fala local](https://superclonica.com/pt/compare/kokoro)
- [Piper TTS ou SuperClonica: aparelhos pequenos ou vozes sob medida](https://superclonica.com/pt/compare/piper)
- [Coqui XTTS-v2 ou SuperClonica: uma alternativa ao Coqui TTS](https://superclonica.com/pt/compare/xtts)
- [Chatterbox TTS ou SuperClonica: clonagem na hora ou um arquivo de voz treinado](https://superclonica.com/pt/compare/chatterbox)

## Perguntas frequentes

### A API é compatível com o endpoint de voz da OpenAI?

Não. Ela tem seu próprio formato JSON simples: text, voice, lang e algumas opções na entrada, um arquivo WAV na saída. Um pequeno adaptador no seu código ou proxy pode converter outros formatos para ele.

### Preciso de uma GPU?

Não. A imagem cpu roda em um processador comum, e uma frase curta leva bem menos de um segundo. Uma GPU NVIDIA com a imagem cuda é várias vezes mais rápida e serve para grandes volumes.

### Quantas requisições ela atende ao mesmo tempo?

As requisições são geradas em lanes, cópias do modelo; com uma só, elas esperam a vez. Defina SUPERCLONICA_LANES (até 8) para atender várias ao mesmo tempo; na CPU as lanes dividem os núcleos, na GPU elas a aproveitam melhor.

### Funciona sem internet?

Sim, depois da primeira inicialização. O modelo fica no volume /models e, a partir daí, o servidor não precisa de conexão; só é preciso internet para baixar a imagem e o modelo.

- [Ver vozes para a sua API](https://superclonica.com/pt/explore)
- [Outras formas de instalar o motor](https://superclonica.com/pt/superclonica)

## Fontes

- [Imagem Docker da SuperClonica (Docker Hub)](https://hub.docker.com/r/superclonica/superclonica)
- [Instalação do NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
- [Motor SuperClonica (PyPI)](https://pypi.org/project/superclonica-cpu/)
- [Cartão do modelo Supertonic 3 (Hugging Face)](https://huggingface.co/supertone-oss-archive/supertonic-3)
- [Vozes gratuitas do Supertonic 3 (GitHub)](https://github.com/superclonica/supertonic-voices)
- [SuperClonica](https://superclonica.com/pt/)
- [Catálogo de vozes de IA para texto em fala](https://superclonica.com/pt/explore)
- [Pedidos de vozes personalizadas](https://superclonica.com/pt/requests)
- [Como funciona: vozes, TTS local e treinamento](https://superclonica.com/pt/guide)
- [Instale o motor rápido para o Supertonic 3](https://superclonica.com/pt/superclonica)
- [Quem somos: entusiastas de TTS](https://superclonica.com/pt/about)
- [Contato, suporte e denúncias de vozes](https://superclonica.com/pt/contacts)
- [Política de privacidade e dados](https://superclonica.com/pt/privacy)
- [Termos de uso da plataforma](https://superclonica.com/pt/terms)
- [Texto para fala](https://superclonica.com/pt/text-to-speech)