GUÍA

API de texto a voz autoalojada en Docker

Una API de texto a voz en tu propio servidor convierte texto en audio para cualquier programa que pueda enviar una petición HTTP: una web, un bot, el backend de un juego o un script en cualquier lenguaje. El texto no sale de tu máquina y no se paga por carácter.

Esta guía muestra cómo ejecutar el motor SuperClonica, basado en el modelo abierto Supertonic 3, como servidor HTTP en Docker: el arranque en CPU o GPU NVIDIA, las peticiones con voces integradas y personalizadas, y la preparación para un uso real. La imagen y el motor son nuestros, así que lo indicamos cuando hablamos de nosotros.

Ver voces para tu API Otras formas de instalar el motor

Por qué ejecutar la síntesis de voz por tu cuenta

Con las API de voz en la nube es fácil empezar, pero cada petición envía tu texto al proveedor y se cobra por carácter. Una API autoalojada cambia eso por un servidor que gestionas tú.

  • Privacidad: los textos y el audio se quedan en tu hardware, algo importante para documentos internos, mensajes y datos de usuarios.
  • Coste: una vez pagado el hardware, la voz es gratis; los textos largos y los grandes volúmenes no suben la factura.
  • Cualquier cliente: un solo endpoint HTTP sirve igual a Python, JavaScript, Go, PHP, C# o un script de shell.
  • Sin conexión: una vez descargado el modelo, el servidor no necesita internet.

Iniciar el servidor

En cualquier CPU: docker run -d --name tts -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cpu. En una GPU NVIDIA, instala NVIDIA Container Toolkit y usa docker run -d --name tts --gpus all -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cuda; la imagen trae CUDA y cuDNN, y el host solo necesita el controlador.

El primer arranque descarga el modelo Supertonic 3, de unos 385 MB, en el volumen superclonica-models; los siguientes lo reutilizan. El servidor está listo cuando GET http://localhost:8000/health responde con su estado, su versión y el dispositivo en uso. La imagen tiene su propia comprobación de salud, así que docker ps muestra cuándo está lista.

Enviar una petición

POST /synthesize recibe JSON y responde con un archivo WAV mono de 16 bits: curl -X POST http://localhost:8000/synthesize -H "Content-Type: application/json" -d '{"text": "¡Hola desde mi propio servidor!", "voice": "F1", "lang": "es"}' -o hola.wav. Las cabeceras X-Sample-Rate y X-Duration-Seconds describen el audio.

Los campos son text, voice, lang, seed y normalize. voice es una de las diez voces integradas, de M1 a M5 y de F1 a F5, o una voz personalizada; lang es el idioma del texto, uno de los 31 idiomas del modelo (el chino no está entre ellos). Una semilla fija devuelve el mismo audio para el mismo texto, y normalize iguala el volumen. GET /voices lista las voces integradas y los idiomas, y /docs muestra la documentación interactiva de la API.

Usar voces personalizadas

Una voz de Supertonic 3 es un archivo JSON de unos 0,3 MB. Hay voces gratuitas con muestras de audio en el repositorio superclonica/supertonic-voices de GitHub, y el catálogo de SuperClonica tiene más de 170, cada una con una demo en línea gratuita.

La voz va en la petición como el propio objeto JSON, en el campo voice, así que el servidor no guarda archivos de voz. Como el objeto es grande, arma la petición en un archivo y envíala con curl -d @request.json, o desde el código: carga la voz con json.load en Python o JSON.parse en JavaScript y envíala junto con el texto. El cuerpo de una petición puede ocupar hasta 2 MB.

Configuración

El servidor lee su configuración de variables de entorno, pasadas con -e en docker run o en un archivo Compose.

  • SUPERCLONICA_API_KEY: si está definida, /synthesize y /voices exigen la cabecera Authorization: Bearer seguida de la clave.
  • SUPERCLONICA_LANES: copias del modelo, de 1 a 8 (1 por defecto); cada una atiende una petición a la vez y necesita su propia memoria.
  • SUPERCLONICA_DEVICE: auto, cuda o cpu (auto por defecto: la GPU si la hay).
  • SUPERCLONICA_THREADS: hilos de CPU (por defecto uno por núcleo físico).
  • SUPERCLONICA_MAX_TEXT: el texto más largo en caracteres (5000 por defecto).

Antes de llevarla a producción

Unos pocos hábitos mantienen rápida y segura una API de voz autoalojada.

  • Conserva el volumen /models para que los reinicios no vuelvan a descargar el modelo, e inicia el contenedor con --restart unless-stopped.
  • No expongas el puerto 8000 a internet tal cual: define una clave de API y pon el servidor detrás de un proxy inverso con HTTPS, o mantenlo en una red privada.
  • Divide tú mismo los textos largos en párrafos si necesitas progreso o streaming; el motor ya lee un texto largo en fragmentos naturales de hasta 160 caracteres.
  • Guarda en caché el audio de los textos que se repiten, como las frases de la interfaz: el mismo texto, voz y semilla siempre dan el mismo archivo.
  • Mide en tu hardware: en nuestras pruebas una frase corta tardó 0,12 s en una RTX 5070 Ti y 0,43 s en cuatro hilos de un Ryzen 7 5800X.

Licencias

El motor SuperClonica y la imagen se publican bajo Apache License 2.0. El modelo Supertonic 3 está bajo OpenRAIL-M, una licencia libre de regalías con una lista de usos prohibidos en lugar de una cláusula no comercial: no uses la voz para hacerte pasar por alguien sin su consentimiento, para engañar o para acosar, e indica que el audio es generado por máquina cuando importe.