{"kind":"guides","slug":"text-to-speech-api-docker","path":"/guides/text-to-speech-api-docker","title":"API de texto para fala auto-hospedada Docker | SuperClonica","description":"Sua própria API HTTP de texto para fala no Docker, em CPU ou GPU NVIDIA: inicie o servidor, envie requisições com suas vozes, defina uma chave de API e escale.","h1":"API de texto para fala auto-hospedada no Docker","intro":"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.\n\nEste 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.","sections":[{"heading":"Por que rodar a síntese de voz por conta própria","paragraphs":["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."],"points":["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."]},{"heading":"Iniciar o servidor","paragraphs":["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."]},{"heading":"Enviar uma requisição","paragraphs":["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."]},{"heading":"Usar vozes personalizadas","paragraphs":["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."]},{"heading":"Configurações","paragraphs":["O servidor lê as configurações de variáveis de ambiente, passadas com -e no docker run ou em um arquivo Compose."],"points":["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)."]},{"heading":"Antes de colocar em produção","paragraphs":["Alguns hábitos mantêm uma API de voz auto-hospedada rápida e segura."],"points":["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."]},{"heading":"Licenças","paragraphs":["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."]}],"faq":[{"question":"A API é compatível com o endpoint de voz da OpenAI?","answer":"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."},{"question":"Preciso de uma GPU?","answer":"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."},{"question":"Quantas requisições ela atende ao mesmo tempo?","answer":"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."},{"question":"Funciona sem internet?","answer":"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."}],"cta":{"catalog":"Ver vozes para a sua API","install":"Outras formas de instalar o motor"},"sources":[{"label":"Imagem Docker da SuperClonica (Docker Hub)","url":"https://hub.docker.com/r/superclonica/superclonica"},{"label":"Instalação do NVIDIA Container Toolkit","url":"https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html"},{"label":"Motor SuperClonica (PyPI)","url":"https://pypi.org/project/superclonica-cpu/"},{"label":"Cartão do modelo Supertonic 3 (Hugging Face)","url":"https://huggingface.co/supertone-oss-archive/supertonic-3"},{"label":"Vozes gratuitas do Supertonic 3 (GitHub)","url":"https://github.com/superclonica/supertonic-voices"}],"published":"2026-10-22","updated":"2026-10-22","pages":[{"slug":"offline-text-to-speech","path":"/guides/offline-text-to-speech","h1":"Como converter texto em fala offline no seu computador"},{"slug":"voice-cloning","path":"/guides/voice-cloning","h1":"Clonagem de voz: como conseguir uma voz parecida com uma gravação"},{"slug":"best-free-tts-models","path":"/guides/best-free-tts-models","h1":"Os melhores modelos de texto para fala grátis para uso local em 2026"},{"slug":"text-to-speech-for-videos","path":"/guides/text-to-speech-for-videos","h1":"Texto para fala para vídeos, audiolivros, jogos e apps"},{"slug":"supertonic-3-voices","path":"/guides/supertonic-3-voices","h1":"Vozes do Supertonic 3: onde conseguir vozes próprias e como usá-las"},{"slug":"python-text-to-speech","path":"/guides/python-text-to-speech","h1":"Texto para fala em Python: offline, grátis e com vozes naturais"},{"slug":"text-to-speech-api-docker","path":"/guides/text-to-speech-api-docker","h1":"API de texto para fala auto-hospedada no Docker"}],"related":[{"slug":"text-to-speech","path":"/text-to-speech","h1":"Texto para fala que roda no seu próprio computador"},{"slug":"supertonic","path":"/compare/supertonic","h1":"Supertonic vs SuperClonica: o mesmo modelo, mais rápido e limpo"},{"slug":"fish-audio","path":"/compare/fish-audio","h1":"Fish Audio e Fish Speech comparados ao SuperClonica"},{"slug":"omnivoice","path":"/compare/omnivoice","h1":"OmniVoice ou SuperClonica: mais idiomas ou mais velocidade"},{"slug":"qwen3-tts","path":"/compare/qwen3-tts","h1":"Qwen3-TTS ou SuperClonica para texto para fala local"},{"slug":"voxcpm","path":"/compare/voxcpm","h1":"VoxCPM 2 ou SuperClonica: som de estúdio ou velocidade no CPU"},{"slug":"f5-tts","path":"/compare/f5-tts","h1":"F5-TTS ou SuperClonica: clonagem zero-shot ou fala rápida no CPU"},{"slug":"elevenlabs","path":"/compare/elevenlabs","h1":"Uma alternativa offline ao ElevenLabs"},{"slug":"kokoro","path":"/compare/kokoro","h1":"Kokoro TTS ou SuperClonica: dois modelos pequenos de texto para fala local"},{"slug":"piper","path":"/compare/piper","h1":"Piper TTS ou SuperClonica: aparelhos pequenos ou vozes sob medida"},{"slug":"xtts","path":"/compare/xtts","h1":"Coqui XTTS-v2 ou SuperClonica: uma alternativa ao Coqui TTS"},{"slug":"chatterbox","path":"/compare/chatterbox","h1":"Chatterbox TTS ou SuperClonica: clonagem na hora ou um arquivo de voz treinado"}]}