{"kind":"guides","slug":"text-to-speech-api-docker","path":"/guides/text-to-speech-api-docker","title":"Self-Hosted Text to Speech API in Docker | SuperClonica","description":"Run your own text-to-speech HTTP API in Docker on a CPU or NVIDIA GPU: start the server, send requests with custom voices, set an API key and scale it.","h1":"Self-hosted text-to-speech API in Docker","intro":"A text-to-speech API on your own server turns text into audio for any program that can send an HTTP request: a website, a bot, a game backend or a script in any language. The text never leaves your machine, and there is no charge per character.\n\nThis guide shows how to run the SuperClonica engine, built on the open Supertonic 3 model, as an HTTP server in Docker: starting it on a CPU or an NVIDIA GPU, sending requests with built-in and custom voices, and preparing it for real use. The image and the engine are ours, so we say where something is.","sections":[{"heading":"Why run text to speech yourself","paragraphs":["Cloud speech APIs are easy to start with, but every request sends your text to the provider and is billed by the character. A self-hosted API trades that for a server you manage."],"points":["Privacy: texts and audio stay on your hardware, which matters for internal documents, messages and user data.","Cost: after the hardware, speech is free; long texts and large volumes do not raise the bill.","Any client: one HTTP endpoint serves Python, JavaScript, Go, PHP, C# or a shell script alike.","Offline: once the model is downloaded, the server needs no internet connection."]},{"heading":"Start the server","paragraphs":["On any CPU: docker run -d --name tts -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cpu. On an NVIDIA GPU, install the NVIDIA Container Toolkit and use docker run -d --name tts --gpus all -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cuda; the image brings CUDA and cuDNN, the host needs only the driver.","The first start downloads the Supertonic 3 model, about 385 MB, into the superclonica-models volume; later starts reuse it. The server is ready when GET http://localhost:8000/health answers with its status, version and the device in use. The image has a health check of its own, so docker ps shows when it is healthy."]},{"heading":"Send a request","paragraphs":["POST /synthesize takes JSON and answers with a 16-bit mono WAV file: curl -X POST http://localhost:8000/synthesize -H \"Content-Type: application/json\" -d '{\"text\": \"Hello from my own server!\", \"voice\": \"F1\", \"lang\": \"en\"}' -o hello.wav. The headers X-Sample-Rate and X-Duration-Seconds describe the audio.","The fields are text, voice, lang, seed and normalize. voice is one of the ten built-in voices, M1 to M5 and F1 to F5, or a custom voice; lang is the language of the text, one of the model's 31 languages (Chinese is not among them). A fixed seed gives the same audio for the same text again, and normalize evens the loudness. GET /voices lists the built-in voices and languages, and /docs shows the interactive API documentation."]},{"heading":"Use custom voices","paragraphs":["A Supertonic 3 voice is a JSON file of about 0.3 MB. Free voices with audio samples are in the superclonica/supertonic-voices repository on GitHub, and the SuperClonica catalog has 170+ more, each with a free online demo.","The voice goes into the request as the JSON object itself, in the voice field, so the server keeps no voice files. Because the object is large, build the request in a file and send it with curl -d @request.json, or in code: load the voice with json.load in Python or JSON.parse in JavaScript and post it together with the text. A request body may be up to 2 MB."]},{"heading":"Settings","paragraphs":["The server reads its settings from environment variables, passed with -e in docker run or in a Compose file."],"points":["SUPERCLONICA_API_KEY: when set, /synthesize and /voices require the header Authorization: Bearer followed by the key.","SUPERCLONICA_LANES: copies of the model, from 1 to 8 (default 1); each renders one request at a time, and each needs its own memory.","SUPERCLONICA_DEVICE: auto, cuda or cpu (default auto: the GPU when there is one).","SUPERCLONICA_THREADS: CPU threads (default one per physical core).","SUPERCLONICA_MAX_TEXT: the longest text in characters (default 5000)."]},{"heading":"Before you put it into production","paragraphs":["A few habits keep a self-hosted speech API fast and safe."],"points":["Keep the /models volume, so restarts do not download the model again, and start the container with --restart unless-stopped.","Do not expose port 8000 to the internet as it is: set an API key and put the server behind a reverse proxy with HTTPS, or keep it on a private network.","Split long texts into paragraphs on your side if you need progress or streaming; the engine already voices a long text in natural pieces of up to 160 characters.","Cache audio for texts that repeat, such as interface phrases: the same text, voice and seed always give the same file.","Measure on your hardware: in our tests a short phrase took 0.12 s on an RTX 5070 Ti and 0.43 s on four threads of a Ryzen 7 5800X."]},{"heading":"Licenses","paragraphs":["The SuperClonica engine and the image are released under the Apache License 2.0. The Supertonic 3 model is under OpenRAIL-M, a royalty-free license with a list of prohibited uses rather than a non-commercial clause: do not use speech to impersonate someone without consent, to deceive or to harass, and say that audio is machine-generated where that matters."]}],"faq":[{"question":"Is the API compatible with the OpenAI speech endpoint?","answer":"No. It has its own simple JSON format: text, voice, lang and a few options in, a WAV file out. A small adapter in your code or proxy can map other formats to it."},{"question":"Do I need a GPU?","answer":"No. The cpu image runs on an ordinary processor, and a short phrase takes well under a second. An NVIDIA GPU with the cuda image is several times faster and suits large volumes."},{"question":"How many requests can it handle at once?","answer":"Requests are rendered on lanes, copies of the model; with one lane they take turns. Set SUPERCLONICA_LANES (up to 8) to serve several at once; on a CPU the lanes share the processor cores, on a GPU they fill it better."},{"question":"Does it work without internet?","answer":"Yes, after the first start. The model is stored in the /models volume, and from then on the server needs no connection; only pulling the image and the first download need internet."}],"cta":{"catalog":"Browse voices for your API","install":"Other ways to install the engine"},"sources":[{"label":"SuperClonica Docker image (Docker Hub)","url":"https://hub.docker.com/r/superclonica/superclonica"},{"label":"NVIDIA Container Toolkit installation guide","url":"https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html"},{"label":"SuperClonica engine (PyPI)","url":"https://pypi.org/project/superclonica-cpu/"},{"label":"Supertonic 3 model card (Hugging Face)","url":"https://huggingface.co/supertone-oss-archive/supertonic-3"},{"label":"Free Supertonic 3 voices (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":"How to convert text to speech offline on your computer"},{"slug":"voice-cloning","path":"/guides/voice-cloning","h1":"Voice cloning: how to get a voice that sounds like a recording"},{"slug":"best-free-tts-models","path":"/guides/best-free-tts-models","h1":"The best free text-to-speech models for local use in 2026"},{"slug":"text-to-speech-for-videos","path":"/guides/text-to-speech-for-videos","h1":"Text to speech for videos, audiobooks, games and apps"},{"slug":"supertonic-3-voices","path":"/guides/supertonic-3-voices","h1":"Supertonic 3 voices: where to get custom voices and how to use them"},{"slug":"python-text-to-speech","path":"/guides/python-text-to-speech","h1":"Text to speech in Python: offline, free and with natural voices"},{"slug":"text-to-speech-api-docker","path":"/guides/text-to-speech-api-docker","h1":"Self-hosted text-to-speech API in Docker"}],"related":[{"slug":"text-to-speech","path":"/text-to-speech","h1":"Text-to-speech that runs on your own computer"},{"slug":"supertonic","path":"/compare/supertonic","h1":"Supertonic vs SuperClonica: same model, faster and cleaner"},{"slug":"fish-audio","path":"/compare/fish-audio","h1":"Fish Audio and Fish Speech vs SuperClonica"},{"slug":"omnivoice","path":"/compare/omnivoice","h1":"OmniVoice vs SuperClonica: more languages or more speed"},{"slug":"qwen3-tts","path":"/compare/qwen3-tts","h1":"Qwen3-TTS vs SuperClonica for local text-to-speech"},{"slug":"voxcpm","path":"/compare/voxcpm","h1":"VoxCPM 2 vs SuperClonica: studio sound or CPU speed"},{"slug":"f5-tts","path":"/compare/f5-tts","h1":"F5-TTS vs SuperClonica: zero-shot cloning or fast CPU speech"},{"slug":"elevenlabs","path":"/compare/elevenlabs","h1":"An offline alternative to ElevenLabs"},{"slug":"kokoro","path":"/compare/kokoro","h1":"Kokoro TTS vs SuperClonica: two small models for local speech"},{"slug":"piper","path":"/compare/piper","h1":"Piper TTS vs SuperClonica: tiny devices or custom voices"},{"slug":"xtts","path":"/compare/xtts","h1":"Coqui XTTS-v2 vs SuperClonica: a Coqui TTS alternative"},{"slug":"chatterbox","path":"/compare/chatterbox","h1":"Chatterbox TTS vs SuperClonica: instant cloning or a trained voice file"}]}