Documentación Técnica de la API de Texto a Voz

Por equipo editorial CuentoVoz · Actualizado 2026-11-19

Bienvenido a la documentación de CuentoVoz, la API de texto a voz diseñada específicamente para desarrolladores independientes que crean historias infantiles y audiolibros. Aquí encontrarás una guía técnica clara para integrar nuestra generación de audio en tus proyectos, utilizando un endpoint compatible con el estándar de la industria y SDKs existentes.

Esta página te guía paso a paso desde la obtención de tu clave API hasta la ejecución de tus primeras solicitudes con cURL o Python. Exploraremos las ocho voces, los formatos de audio disponibles, los límites de uso y los errores comunes, asegurando que tengas todo lo necesario para producir narraciones sin complicaciones innecesarias.

Documentación Técnica de la API de Texto a Voz

Preguntas frecuentes

¿Qué es un base_url en la API?

Es la dirección base para las solicitudes HTTP. Configura tu SDK o cliente HTTP hacia https://api.21viptaka.info/v1. Esto permite usar el mismo formato de solicitud que OpenAI, solo cambiando la URL de origen para conectar con nuestros servidores de síntesis de voz.

¿Puedo usar la misma clave en múltiples proyectos?

Sí, tu clave API es válida para todos tus proyectos. Solo hay una clave activa por cuenta. Si necesitas revocarla, puedes emitir una nueva en cualquier momento; la anterior dejará de funcionar inmediatamente, asegurando que solo tus proyectos autorizados usen el servicio.

¿Cuántas voces puedo solicitar a la vez?

Puedes solicitar cualquier combinación de las 8 voces disponibles (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion). No hay límite de tipos de voz simultáneos, pero sí un límite de 60 solicitudes por minuto por clave. Cada solicitud genera un archivo de audio independiente.

¿Qué formato es mejor para historias infantiles?

MP3 es ideal por su equilibrio entre calidad y tamaño de archivo. También puedes elegir WAV o FLAC para máxima fidelidad sin pérdida. Los formatos Opus y PCM están disponibles según tus necesidades de almacenamiento o reproducción. La elección depende de tu reproductor final.

¿Es necesario instalar librerías adicionales?

No es obligatorio. Puedes usar HTTP estándar (curl, fetch) o el SDK de OpenAI ajustando la base_url. No ofrecemos SDK propio ni móvil. Cualquier cliente HTTP compatible con JSON funciona perfectamente para enviar texto y recibir el archivo de audio generado directamente.

¿Cómo se manejan textos mayores a 4096 caracteres?

Debes dividir el texto en fragmentos de máximo 4096 caracteres. Envía cada fragmento en una solicitud POST separada y une los archivos de audio resultantes. Esto asegura que cada solicitud cumpla con el límite de longitud permitido por la API para una síntesis correcta.

¿Qué significa el código de error 429?

Indica que has excedido el límite de 60 solicitudes por minuto. Si es tu primera cuenta sin recarga, el límite es de 10 por minuto. Espera a que el contador se reinicie; la recarga no cambia el límite de 60 solicitudes por minuto.

¿Puedo usar la API en un servidor backend?

Sí, está diseñada para uso desde servidores backend. Envías el texto desde tu servidor y recibes el audio. No hay streaming ni WebSocket, por lo que debes manejar la solicitud síncrona o asíncrona según la arquitectura de tu aplicación de historias infantiles.

¿Se soporta streaming de audio en tiempo real?

No. La API devuelve el archivo completo una vez terminada la síntesis. No hay transmisión parcial ni WebSocket. Debes esperar a que la solicitud se complete para recibir el audio, lo cual puede tardar unos segundos dependiendo de la longitud del texto y la carga del servidor.

¿Cuánto tarda en generarse un audio?

Rápidamente, aproximadamente en tiempo real (25 caracteres por segundo). Las frases cortas tardan unos segundos. Bajo carga, las solicitudes pueden hacer cola. Si el texto es largo, el tiempo total será proporcional a la duración del audio generado sin retrasos significativos adicionales.

¿Qué es un modelo tts-1-hd?

Es el modelo de alta definición de nuestra API. Usa el mismo motor que tts-1 y tiene el mismo precio. El precio es idéntico: $0.01 por cada 1.000 caracteres. Puedes elegirlo para obtener una narración más rica y detallada para tus historias infantiles.

¿Puedo cambiar la velocidad después de generar?

No. La velocidad (0.25–4.0) se define en la solicitud inicial. Una vez generado el audio, la velocidad está fija en el archivo. Si necesitas otro ritmo, debes realizar una nueva solicitud con el parámetro de velocidad ajustado a tu preferencia para obtener un archivo diferente.

¿Cómo valido mi clave de autenticación?

Incluye tu clave en el encabezado Authorization: Bearer tts-... en cada solicitud POST. Si la clave es válida y tienes saldo, la solicitud se procesará. Si falla la autenticación o el saldo es insuficiente, recibirás un error sin cargo. Verifica tu clave en /get-api-key/.

¿Hay versión de la API para móviles?

No hay un SDK específico para móviles. Usa el SDK de OpenAI con la base_url ajustada o HTTP estándar desde tu app móvil. La API es RESTful y funciona en cualquier entorno que pueda enviar solicitudes HTTP JSON, incluyendo aplicaciones iOS y Android.

Primera solicitud

curl

curl https://api.21viptaka.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.21viptaka.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.21viptaka.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafemenino
novafemenino
lunafemenino
sagefemenino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Obtención de la clave API

Ilustración de onda de sonido para: Obtención de la clave API

Accede a la generación de audio para tus historias infantiles registrándote en /get-api-key/. Puedes elegir autenticación con Google o crear una cuenta con email y contraseña.

Una vez dentro, el panel muestra tu clave API, el saldo disponible y ejemplos de código listos para copiar.

Registro con Google o email

Registro con Google o email

El registro es inmediato. Si usas Google, recibes $0.50 de crédito de prueba válido por 7 días. Con email y contraseña, la cuenta se crea sin crédito inicial.

Cada sitio funciona de forma independiente, por lo que las credenciales son específicas de 21viptaka.info.

Ubicación de la clave en el dashboard

Ubicación de la clave en el dashboard

Tu clave empieza por 'tts-...' y se muestra en la página principal del panel junto a tu balance.

Usa esta clave en el encabezado Authorization: Bearer para todas las peticiones a la API.

  • La clave se muestra claramente en el panel de control.
  • Es necesaria para autenticar cada solicitud POST.

Gestión y revocación de claves

Dispones de una única clave activa por cuenta. Si la comprometes o deseas una nueva, emite una nueva desde el panel.

La clave anterior deja de funcionar inmediatamente al generar la nueva, sin período de transición.

Primera solicitud con cURL

Ilustración de onda de sonido para: Primera solicitud con cURL

Genera audio con una simple petición HTTP. Este método directo es ideal para pruebas rápidas o integración en scripts simples sin dependencias adicionales.

Asegúrate de tener una clave API válida y suficiente saldo. La API devuelve el archivo de audio directamente en el cuerpo de la respuesta.

Ejemplo básico de POST

Usa cURL para enviar tu texto a la API. Reemplaza tu_api_key con la clave de tu cuenta y ajusta el texto o la voz según necesites.

Body JSON con parámetros

El cuerpo debe ser JSON con los campos model, input, voice y response_format. El campo input acepta hasta 4096 caracteres. Si no especificas idioma, la API intenta adivinarlo, pero es mejor definirlo explícitamente para textos en latín que no sean inglés.

  • model: "tts-1" o "tts-1-hd"
  • input: tu texto (máx. 4096 chars)
  • voice: aria, nova, luna, sage, felix, milo, atlas u orion
  • response_format: mp3, wav, opus, flac o pcm
  • speed: opcional, entre 0.25 y 4.0

Manejo de respuestas exitosas

Una respuesta 200 contiene el archivo de audio binario. Guarda directamente este flujo en un archivo local. Si la síntesis falla, la API devuelve un error JSON y no se cobra el crédito.

Integración con SDK de OpenAI

Ilustración de onda de sonido para: Integración con SDK de OpenAI

El SDK de OpenAI para Python es la forma más sencilla de integrar CuentoVoz. Solo necesitas ajustar la URL base para que apunte a tu instancia independiente, manteniendo la misma estructura de código que ya conoces.

Configuración del base_url

Debes inicializar la clase OpenAI proporcionando tu clave API y modificando el atributo base_url hacia https://api.21viptaka.info/v1. Esto permite que las librerías oficiales reconozcan tus endpoints sin cambios mayores en la lógica de tu aplicación.

Uso de la clase Speech

Una vez configurado, utiliza la clase client.audio.speech para enviar tu texto. La API devolverá el archivo de audio directamente en la respuesta, listo para guardarse o reproducirse en memoria.

Ejemplo en Python

Importa la librería y crea el cliente con tu clave. Llama a create pasando el modelo, la voz elegida y el texto. El método stream_to_file facilita guardar el resultado en tu servidor.

  • Instala la dependencia: pip install openai
  • Clave: Authorization: Bearer tts-...
  • Modelos soportados: tts-1 y tts-1-hd

Endpoints disponibles

Ilustración de onda de sonido para: Endpoints disponibles

La API de CuentoVoz expone tres endpoints principales para interactuar con el servicio de síntesis de voz. Estos puntos finales permiten desde la inspección de recursos disponibles hasta la generación directa de audio, facilitando la integración en flujos de trabajo de desarrollo de historias infantiles y audiolibros.

GET /v1/voices para listar opciones

Utiliza este endpoint para obtener la lista completa de voces disponibles, junto con sus idiomas y formatos soportados. Puedes identificar las 8 presets (como Aria o Felix) y verificar las 23 lenguas admitidas antes de realizar tu primera solicitud.

  • Devuelve metadatos de cada voz y sus capacidades.

GET /v1/models para detalles

Consulta este punto final para confirmar los modelos actuales disponibles, típicamente tts-1 y tts-1-hd. Esta información es útil para asegurar la compatibilidad con tu código antes de enviar solicitudes de síntesis.

POST /v1/audio/speech para generar

Este es el endpoint central donde envías tu texto y recibes el archivo de audio. Requiere un cuerpo JSON con el modelo, el texto (hasta 4096 caracteres), la voz deseada y el formato de respuesta. Es aquí donde ocurre la magia de la conversión de texto a audio.

  • Endpoint principal de generación de audio.

Parámetros de la petición

Ilustración de onda de sonido para: Parámetros de la petición

Configura el modelo y el input para definir la calidad y el contenido de tu narración. Ajusta el formato y la velocidad para que el audio se integre perfectamente en tu historia infantil o audiolibro.

Cada parámetro afecta directamente la experiencia de escucha. Usa los valores correctos para evitar errores y obtener resultados consistentes en cada generación.

Modelo tts-1 y tts-1-hd

El campo model acepta "tts-1" o "tts-1-hd". Ambos usan el mismo motor de síntesis y tienen idéntico precio. La elección es puramente estética, ya que ambos modelos usan el mismo motor de síntesis y tienen idéntico precio.

Entrada de texto y voz

Proporciona tu texto en input, con un límite estricto de 4096 caracteres por petición. Asigna una de las 8 voces predefinidas en voice (como aria o luna) para dar personalidad a la narración. Si el texto está en español, especifica language como "es" para evitar que se interprete como inglés por defecto.

Formato de respuesta y velocidad

Elige response_format entre mp3, wav, opus, flac o pcm según tus necesidades de almacenamiento. Ajusta la speed entre 0.25 y 4.0 para controlar el ritmo de la lectura. Valores bajos ralentizan la voz para historias más pausadas, mientras que valores altos aceleran la narración.

Parámetros de la petición

Límites y rendimiento

Ilustración de onda de sonido para: Límites y rendimiento

La API está diseñada para ser confiable bajo carga moderada, pero requiere que los desarrolladores respeten los límites de velocidad y longitud para garantizar una generación fluida. Conocer estas restricciones evita interrupciones inesperadas en la producción de audiolibros o cuentos infantiles.

60 peticiones por minuto

El límite estándar es de 60 solicitudes por minuto por clave API. Antes de realizar tu primera recarga, este límite se reduce a 10 solicitudes por minuto para controlar el uso durante la prueba gratuita.

Si excedes este límite, la API devolverá un error HTTP 429 (Too Many Requests).

  • 60 req/min con clave activa y saldo suficiente.
  • 10 req/min antes del primer depósito.
  • Error 429 si se excede el límite.

Límite de 4096 caracteres

Cada solicitud POST acepta un máximo de 4096 caracteres en el campo input, incluyendo espacios y puntuación. Para textos más largos, como un cuento completo, debes dividir el texto en partes de este tamaño y unir los archivos de audio resultantes.

La velocidad de generación es aproximadamente de 25 caracteres por segundo, lo que equivale a tiempo real para textos extensos. Las frases cortas pueden tardar unos segundos adicionales en procesarse.

  • Máximo 4096 caracteres por petición.
  • Incluye espacios y puntuación.
  • Velocidad: ~25 caracteres/segundo.

Procesamiento en cola

Las solicitudes se procesan secuencialmente dentro de la capacidad disponible. Bajo alta demanda, una petición puede esperar en una cola antes de comenzar la síntesis.

Esto no afecta la integridad del audio generado, pero puede aumentar ligeramente la latencia percibida si muchas solicitudes se envían simultáneamente. El sistema gestiona la cola automáticamente sin pérdida de datos.

  • Procesamiento secuencial.
  • Cola automática bajo carga.
  • Sin pérdida de integridad de audio.

Manejo de errores comunes

Ilustración de onda de sonido para: Manejo de errores comunes

Es importante distinguir entre errores de formato y fallos de síntesis. Cuando la API devuelve un error, la solicitud no se cobra, devolviéndose el crédito íntegramente. Esto garantiza que no pagues por audio que nunca se generó.

Códigos de estado HTTP

El servicio responde con códigos estándar. Un 200 OK indica que el archivo de audio está listo para descargar. Los errores de validación (como un texto vacío) devuelven 400 Bad Request, mientras que los errores internos del servidor se señalan con 500. Revisa siempre el cuerpo de la respuesta para ver el mensaje de error detallado.

Errores de autenticación

Si la clave no es válida o ha sido revocada, recibirás un 401 Unauthorized. Asegúrate de que tu cabecera Authorization contenga el prefijo Bearer seguido de tu clave única. Si generaste una nueva clave en el dashboard, la anterior deja de funcionar inmediatamente.

Límites de cuota excedidos

Si superas las 60 peticiones por minuto, la API retornará un 429 Too Many Requests. Si no has realizado tu primera recarga, el límite es más restrictivo: 10 solicitudes por minuto. Espera unos segundos antes de reintentar o revisa el saldo de tu cuenta.

Ejemplos de uso avanzado

Ilustración de onda de sonido para: Ejemplos de uso avanzado

Estos ejemplos ilustran cómo controlar aspectos clave de la generación de audio para adaptar la salida a las necesidades específicas de tus historias infantiles o audiolibros. Cada caso muestra la estructura JSON necesaria para obtener el comportamiento deseado.

Cambio de idioma explícito

Aunque el sistema intenta adivinar el idioma basándose en el guion, es recomendable establecer el parámetro language explícitamente para textos en latín que no sean inglés. Esto evita errores de pronunciación en historias multilingües o con nombres propios específicos.

  • Establece language: 'es' para garantizar una pronunciación correcta del español, incluso si el texto contiene palabras en inglés.

Uso de formatos opus y flac

Más allá de mp3 y wav, puedes solicitar formatos opus o flac. El formato FLAC es ideal para archivado de alta fidelidad sin pérdida, mientras que OPUS ofrece una compresión eficiente manteniendo buena calidad para aplicaciones web modernas.

  • Usa response_format: 'flac' para máxima fidelidad en audiolibros.
  • Usa response_format: 'opus' para reducir el ancho de banda en apps móviles.

Ajuste fino de velocidad

El parámetro speed permite ajustar la velocidad entre 0.25 y 4.0. Para historias infantiles, una velocidad ligeramente reducida (ej. 0.9) puede mejorar la claridad narrativa, mientras que valores más altos aceleran la generación de contenido de relleno o transiciones rápidas.

  • Configura speed: 1.0 para un ritmo natural estándar.
  • Reduce a speed: 0.8 para mejorar la comprensión en audiocuentos para niños pequeños.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Ideal para cuentos donde los protagonistas interactúan directamente con el oyente o comparten aventuras en un entorno familiar.

Avatar de la voz aria
ariafemenino
Avatar de la voz nova
novafemenino
Avatar de la voz luna
lunafemenino
Avatar de la voz sage
sagefemenino
Avatar de la voz felix
felixmasculino
Avatar de la voz milo
milomasculino
Avatar de la voz atlas
atlasmasculino
Avatar de la voz orion
orionmasculino

23 idiomas

Cualquier voz puede hablar cualquiera de estos idiomas.

Fuentes y lecturas adicionales

  1. Wikipedia
  2. IETF RFC 7845: Ogg Opus
  3. MDN: Web Speech API
  4. FFmpeg documentation
  5. ISO 639 language codes
  6. Node.js documentation
  7. LibriTTS-R corpus (OpenSLR 141)
  8. OpenAI API reference: create speech
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. openai-node on GitHub
  11. Python documentation
  12. TRON developer hub: TRC-20

Más en este sitio