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.mp3Python (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 | |
|---|---|
aria | femenino |
nova | femenino |
luna | femenino |
sage | femenino |
felix | masculino |
milo | masculino |
atlas | masculino |
orion | masculino |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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
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
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
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-1ytts-1-hd
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
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.

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
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
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.0para un ritmo natural estándar. - Reduce a
speed: 0.8para 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.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
