Preguntas frecuentes
¿Qué formato de autenticación utiliza la API?
La API utiliza autenticación mediante token Bearer en el encabezado Authorization. Debe incluir una clave válida con el prefijo 'tts-'. Cada cuenta dispone de una única clave activa; al emitir una nueva, la anterior deja de funcionar inmediatamente. Esta seguridad garantiza que solo los usuarios autorizados puedan consumir los recursos de síntesis de voz.
¿Es compatible la API con los SDKs oficiales de OpenAI?
Sí, es compatible. La forma del cuerpo de la solicitud es idéntica a la de OpenAI. Solo necesita cambiar la propiedad base_url a https://api.tikviral.info/v1 y utilizar su clave de API. Esto permite usar los SDKs oficiales sin modificar la lógica de llamada, facilitando la integración rápida en sus aplicaciones existentes.
¿Cuál es el tamaño máximo de texto por solicitud?
El límite máximo es de 4096 caracteres por solicitud. Este conteo incluye espacios y puntuación. Si su texto excede este límite, debe dividirlo en partes más pequeñas. Cada parte se procesará individualmente para generar fragmentos de audio que luego se unirán para formar el audio completo de la entrada original.
¿Qué hace si el texto supera los 4096 caracteres?
Debe dividir el texto en fragmentos de hasta 4096 caracteres y realizar múltiples solicitudes. La API devuelve cada fragmento de audio por separado. Su sistema debe unir estos archivos de audio resultantes para reproducir el texto completo. Este enfoque garantiza que se respete el límite técnico por llamada sin perder calidad ni información.
¿Cómo se especifica el idioma del texto?
Puede especificar el idioma mediante el campo opcional language con un código ISO. Si no se establece, el sistema intenta adivinarlo basándose en el script. Para textos en latín que no sean inglés, se recomienda establecer explícitamente el idioma para evitar errores de pronunciación y asegurar la claridad en la síntesis generada.
¿Qué formatos de audio están disponibles?
Los formatos disponibles son mp3, wav, opus, flac y pcm. Puede seleccionar el formato adecuado según sus necesidades de almacenamiento o reproducción. Estos formatos cubren desde la compresión ligera hasta la calidad sin pérdida, permitiendo una integración flexible en diferentes entornos de aplicaciones empresariales y sistemas de voz automatizados.
¿Qué ocurre si se supera el límite de 60 solicitudes por minuto?
El límite es de 60 solicitudes por minuto por clave. Si se supera, las solicitudes adicionales pueden esperar en una cola o ser rechazadas. Inicialmente, antes del primer recargo, el límite es de 10 solicitudes por minuto. Esto puede afectar la latencia en picos de tráfico, por lo que se recomienda gestionar la cola adecuadamente.
¿Se puede cambiar la velocidad de la voz en tiempo real?
La velocidad se configura mediante el parámetro speed en cada solicitud, con un rango de 0.25 a 4.0. No es un ajuste en tiempo real durante la reproducción, sino una propiedad de la generación. Debe establecer el valor deseado en el cuerpo de la solicitud JSON antes de iniciar la síntesis de audio.
¿Cómo se identifica una solicitud fallida?
Las solicitudes fallidas no generan cargos. Si la síntesis falla, el importe se devuelve íntegramente. La API devuelve un código de estado HTTP indicando el error. Puede monitorear el estado de cada solicitud para identificar fallos y reintentar si es necesario, asegurando que solo se facture el audio generado con éxito.
¿Se puede generar audio en formato FLAC?
Sí, el formato FLAC está disponible como opción en el campo response_format. Este formato ofrece compresión sin pérdida, ideal para archivado o procesamiento posterior. Es una de las cinco opciones soportadas junto a MP3, WAV, OPUS y PCM, permitiendo elegir la calidad y el tamaño de archivo según los requisitos del proyecto.
¿Es necesario cerrar la conexión tras cada solicitud?
La API opera mediante HTTP estándar. No requiere mantenimiento de conexiones persistentes complejas como WebSocket. Cada solicitud es independiente y devuelve el archivo de audio o un estado. Puede cerrar la conexión HTTP tras recibir la respuesta, ya que no hay estado de sesión que deba conservarse entre llamadas sucesivas.
¿Qué versión del protocolo HTTP se utiliza?
La API utiliza el protocolo HTTP estándar para las solicitudes POST y GET. Las conexiones se realizan mediante HTTPS para garantizar la seguridad de los datos transmitidos. No se especifica una versión mayoritaria, pero cumple con los estándares web modernos para la interoperabilidad con SDKs y clientes HTTP comunes en entornos empresariales.
¿Se pueden generar varios archivos de audio en paralelo?
Sí, puede realizar múltiples solicitudes simultáneas desde diferentes hilos o procesos. Cada solicitud se procesa independientemente. Sin embargo, bajo carga, las solicitudes pueden esperar en una cola. El límite de 60 solicitudes por minuto se aplica por clave, por lo que debe gestionar la concurrencia para evitar exceder el umbral de tasa.
¿Dónde se pueden ver los modelos disponibles?
Los modelos disponibles se listan en el endpoint GET /v1/models. También puede ver información sobre voces, idiomas y formatos en GET /v1/voices. Los modelos soportados son tts-1 y tts-1-hd, que comparten el mismo motor y precio. Esta información está disponible programáticamente para integrar la selección dinámica en sus aplicaciones.
Primera solicitud
curl
curl https://api.tikviral.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.tikviral.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.tikviral.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 |
Autenticación y configuración inicial
La integración comienza obteniendo una clave API única desde la página /get-api-key/. Cada cuenta se asocia a un solo token activo que autentica todas las solicitudes hacia el endpoint base.
Obtención de la clave API desde /get-api-key/
Acceda a /get-api-key/ para registrar su cuenta mediante Google o correo electrónico. La interfaz muestra la clave activa, el saldo disponible y el ejemplo de cURL inicial para validar la conexión.
- Registro con Google o email + contraseña
- Clave única por cuenta
- Saldo y créditos visibles
Cabecera Authorization: Bearer <tu-clave>
Incluya la cabecera Authorization: Bearer tts-... en cada solicitud POST. El sistema valida el token antes de procesar la síntesis, asegurando que las solicitudes provengan de una cuenta autorizada.
- Formato: Bearer tts-...
- Validación por token
- Solicitud por solicitud
Emisión de nueva clave y revocación instantánea
Genere una nueva clave en cualquier momento desde el panel. La clave anterior deja de funcionar inmediatamente al emitir la nueva, garantizando control de acceso sin demoras en la seguridad.
- Emisión inmediata
- Revocación instantánea
- Una clave activa por cuenta
Endpoint principal de síntesis
El endpoint principal para la generación de audio es POST https://api.tikviral.info/v1/audio/speech. Este método recibe el texto a sintetizar y devuelve un archivo de audio binario en el cuerpo de la respuesta, listo para ser reproducido o almacenado en su infraestructura de voz para asistentes y chatbots.
Método POST a /v1/audio/speech
Utilice el método POST estándar para enviar su carga útil. La API procesa la solicitud y retorna el archivo de audio una vez completada la síntesis. Asegúrese de incluir la cabecera de autorización con su clave Bearer.
Cuerpo JSON: model, input, voice, response_format
El cuerpo de la solicitud debe ser un objeto JSON con los siguientes campos requeridos: model ("tts-1" o "tts-1-hd"), input (el texto a convertir), voice (uno de los 8 presets disponibles) y response_format (mp3, wav, opus, flac o pcm).
El campo input acepta hasta 4096 caracteres. Si el texto excede este límite, debe dividirlo en fragmentos y concatenar los archivos de audio resultantes para mantener la continuidad en sus interacciones automatizadas.
- model: tts-1 o tts-1-hd
- input: texto máximo 4096 caracteres
- voice: aria, nova, luna, sage, felix, milo, atlas, orion
- response_format: mp3, wav, opus, flac, pcm
Límite de 4096 caracteres por solicitud
Cada solicitud individual está estrictamente limitada a 4096 caracteres, incluyendo espacios y puntuación. Para textos más largos, es responsabilidad del cliente dividir la entrada y gestionar la concatenación de los fragmentos de audio generados para evitar interrupciones en la experiencia del usuario final.
Ejemplo de solicitud con cURL
Para verificar la conectividad básica, utilice la siguiente solicitud cURL con la clave API válida. Este comando prueba la integración sin generar audio costoso si se usa un modelo básico, aunque en esta API toda síntesis cuenta caracteres.
Comando básico de prueba de conectividad
Envíe una solicitud POST al endpoint /v1/audio/speech. Reemplace <TU_CLAVE> con su credencial obtenida en /get-api-key/. Esto confirma que la API responde correctamente antes de integrar en producción.
- Método: POST
- URL: https://api.tikviral.info/v1/audio/speech
- Cabecera: Authorization: Bearer <TU_CLAVE>
Parámetros de voz y formato en la petición
Defina el modelo (tts-1 o tts-1-hd), el texto de entrada y la voz deseada (ej. aria, felix). Especifique el formato de respuesta (mp3, wav, opus, flac, pcm). El texto no debe exceder 4096 caracteres.
Manejo de la respuesta binaria de audio
La API devuelve el archivo de audio binario directamente en el cuerpo de la respuesta. Redirija la salida a un archivo local para su reproducción o procesamiento posterior en sus flujos de automatización.
Integración con SDK de OpenAI
La API de VozViral sigue el formato de solicitud de la API de speech de OpenAI, lo que permite aprovechar los SDKs oficiales de OpenAI cambiando la base_url. Al ajustar el parámetro base_url a https://api.tikviral.info/v1, la biblioteca reconoce automáticamente los endpoints estándar.
Modificación del base_url al endpoint de la API
Configure el cliente de OpenAI (Python, Node.js, etc.) apuntando a la URL base de VozViral. Esto redirige las peticiones de síntesis a nuestro endpoint manteniendo la estructura del payload JSON.
Reutilización de clientes oficiales de OpenAI
Utilice las mismas clases de cliente (OpenAI) y métodos (audio.speech.create) que ya conoce su equipo. La autenticación funciona con la cabecera Authorization: Bearer <tu-clave>, manteniendo la lógica de gestión de credenciales existente.
Compatibilidad con métodos estándar de la biblioteca
Todos los parámetros compatibles (model, input, voice, response_format, speed) se mapean directamente. No se requiere adaptación de código para la generación de audio, solo asegurar que la clave API sea válida para este servicio.
Manejo de errores y estados
La API devuelve códigos HTTP estándar para indicar el estado de la solicitud. Un 200 indica éxito, mientras que un 4xx señala errores de cliente (como autenticación incorrecta o parámetros inválidos) y un 5xx indica fallos del servidor.
En caso de error, la respuesta contiene un JSON con un campo 'error' que describe la causa, facilitando la depuración.
Mensaje de error en caso de fallo de síntesis
Cuando la síntesis falla, la respuesta HTTP no es 200. La respuesta HTTP indica el estado. El cuerpo puede incluir un objeto JSON con un mensaje descriptivo que indica la razón del fallo.
Estos mensajes ayudan a identificar la causa del fallo.
- El error incluye un código numérico y un mensaje en texto claro.
- La respuesta indica el estado HTTP.
Devolución de crédito en solicitudes fallidas
Si la síntesis de audio falla por completo, el cargo correspondiente se devuelve íntegramente a la cuenta. Esto asegura que los equipos no paguen por audio no entregado.
La gestión del saldo es automática; no se requiere intervención manual para reclamar el crédito devuelto en caso de fallo técnico confirmado.
- El crédito se restaura en la cuenta inmediatamente después del procesamiento del error.
- Las solicitudes fallidas son gratuitas.

Límites de tasa y concurrencia
La API aplica un límite de 60 solicitudes por minuto por clave activa. Este umbral permite generar audio en flujos de trabajo empresariales.
Para cuentas nuevas, el límite inicial se establece en 10 solicitudes por minuto. Este valor aumenta automáticamente tras la primera recarga de saldo, garantizando que el volumen de producción se ajuste a la capacidad de pago verificada.
Límite de 60 solicitudes por minuto por clave
El límite estándar de 60 solicitudes por minuto aplica a todas las claves activas. Este valor permite la generación de audio para asistentes de voz y chatbots.
Límite inicial de 10 solicitudes por minuto
Las cuentas recién creadas comienzan con un límite de 10 solicitudes por minuto. Este umbral se eleva a 60 solicitudes por minuto tras realizar la primera recarga de saldo mediante USDT en la red TRON.
Procesamiento secuencial bajo carga
Las solicitudes se procesan secuencialmente. Bajo alta carga, una solicitud puede esperar en cola hasta que se libere capacidad de procesamiento. Esto garantiza la integridad de la síntesis, aunque introduce latencia variable en picos de uso.
Se recomienda implementar lógica de reintentos con backoff exponencial en el cliente para manejar esperas inesperadas durante periodos de alta demanda.
Formateo de texto largo
Para textos extensos, el cuerpo de la solicitud se limita a 4096 caracteres. Es necesario implementar una lógica de división que segmente el texto en bloques manejables antes de enviar cada solicitud POST.
La concatenación de los archivos de audio resultantes debe realizarse en el cliente. Dado que las solicitudes se procesan secuencialmente, es fundamental gestionar el orden de los fragmentos para mantener la coherencia narrativa.
División automática en fragmentos de 4096 caracteres
Cada solicitud POST acepta un máximo de 4096 caracteres en el campo input. Los espacios y la puntuación cuentan como caracteres. La división debe respetar los límites de caracteres para evitar truncamientos inesperados en la síntesis.
Se recomienda dividir el texto en oraciones completas o párrafos lógicos para minimizar cortes abruptos en la voz sintética.
Concatenación de archivos de audio resultantes
El API devuelve un archivo de audio por cada solicitud exitosa. La aplicación cliente debe recibir estos binarios y unirlos en un solo archivo final. Este proceso debe ejecutarse después de que todas las solicitudes hayan sido procesadas.
La concatenación debe mantener el formato de audio especificado en response_format para asegurar la compatibilidad con los reproductores de la aplicación empresarial.
Gestión de pausas entre fragmentos
Al unir los fragmentos, se deben gestionar las pausas naturales entre oraciones o párrafos. La síntesis no añade silencio adicional entre solicitudes, por lo que la continuidad acústica depende de la precisión del texto original.
Para una integración robusta, considere añadir un breve silencio artificial si la división corta una frase en un punto inapropiado.
Parámetros avanzados de audio
La API ofrece control programático sobre la síntesis mediante parámetros opcionales que ajustan la velocidad de generación y el formato de salida, permitiendo optimizar el tráfico y la compatibilidad con distintos reproductores.
La especificación del idioma ISO asegura la correcta pronunciación en textos que no utilizan el guion latino, evitando la detección automática que por defecto asume inglés para texto en latín.
Los formatos soportados son mp3, wav, opus, flac y pcm, seleccionables según las necesidades de compresión o calidad sin pérdida de la aplicación empresarial.
Control de velocidad (0.25 a 4.0)
El parámetro speed acepta valores entre 0.25 y 4.0, permitiendo acelerar o ralentizar la voz generada sin alterar el tono.
Esta capacidad es útil para ajustar el ritmo de las respuestas en chatbots o asistentes de voz, manteniendo la naturalidad de la síntesis.
La velocidad afecta directamente el tiempo de procesamiento, pero no consume más caracteres ni créditos adicionales.
Selección de formato: mp3, wav, opus, flac, pcm
El campo response_format permite elegir entre mp3, wav, opus, flac o pcm para la salida de audio.
Los formatos lossless como wav y flac son ideales para archivado o edición posterior, mientras que mp3 y opus optimizan el ancho de banda.
El formato pcm proporciona audio sin comprimir, útil para sistemas que requieren decodificación en tiempo real.
Especificación opcional de idioma ISO
El parámetro language acepta un código ISO para forzar la pronunciación correcta en textos con guion latino que no sean inglés.
Si no se especifica, el sistema detecta el idioma por el guion; el texto en latino sin especificación se trata como inglés por defecto.
Esta especificación es crucial para garantizar la consistencia acústica en aplicaciones multilingües que procesan texto en español, francés o alemán.
- Códigos válidos: es, fr, de, it, pt, ru, zh, ja, ko, ar, hi, tr, sv, no, fi, pl, nl, da, el, he, ms, sw
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. No existe streaming ni transmisión en tiempo real; el audio se genera completo y se devuelve en la respuesta.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
