GUIDE

Self-hosted text-to-speech API in Docker

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.

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

Browse voices for your API Other ways to install the engine

Why run text to speech yourself

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.

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

Start the server

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.

Send a request

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.

Use custom voices

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.

Settings

The server reads its settings from environment variables, passed with -e in docker run or in a Compose file.

  • 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).

Before you put it into production

A few habits keep a self-hosted speech API fast and safe.

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

Licenses

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.