Preguntas frecuentes
¿Qué formato de API utiliza este servicio?
Utilizamos un endpoint POST estándar compatible con la API de OpenAI. Envías texto en formato JSON y recibes un archivo de audio. Esta estructura permite una integración rápida en sistemas IVR o centros de llamada reutilizando librerías compatibles con el formato de solicitud de OpenAI.
¿Cómo se autentican las solicitudes?
Las solicitudes se autentican mediante un token Bearer en el encabezado Authorization. Debes incluir tu clave API única (formato tts-...) en cada petición para validar tu cuenta y asegurar que los caracteres consumidos se carguen correctamente a tu saldo.
¿Qué es el parámetro base_url?
Es la URL base para las llamadas a la API. Debe configurarse como https://api.tk999us.info/v1. Esto permite que las SDKs oficiales, como la de OpenAI, funcionen correctamente apuntando al endpoint correcto para generar los archivos de audio.
¿Cuántos caracteres tiene el límite por solicitud?
El límite es de 4096 caracteres por solicitud. Si tu texto excede este número, debes dividirlo en partes más pequeñas y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres dentro de este límite.
¿Qué voces están disponibles en la API?
Disponemos de 8 voces preestablecidas: Aria, Nova, Luna, Sage, Felix, Milo, Atlas y Orion. Cada una tiene un tono distinto, desde narrador cálido hasta documental profundo, y todas pueden pronunciar los 23 idiomas soportados.
¿Se puede ajustar la velocidad de la voz?
Sí, puedes ajustar la velocidad entre 0.25 y 4.0. Esto permite adaptar la síntesis a las necesidades específicas de tus sistemas IVR, acelerando o ralentizando la voz entre 0.25 y 4.0.
¿Qué formatos de audio se pueden solicitar?
Puedes solicitar audio en los formatos mp3, wav, opus, flac y pcm. Estos formatos estándar facilitan la integración con diferentes plataformas de telefonía y sistemas de respuesta de voz, asegurando compatibilidad amplia con tu infraestructura técnica actual.
¿Cómo se manejan los textos muy largos?
Debes dividir el texto en fragmentos de hasta 4096 caracteres. Luego, envía cada fragmento en solicitudes separadas y une los archivos de audio resultantes. La generación es aproximadamente en tiempo real (25 caracteres por segundo), procesándose secuencialmente y pudiendo esperar en cola bajo carga.
¿Qué significa el código de error 429?
Indica que has excedido el límite de velocidad de 60 solicitudes por minuto por clave. Si es una cuenta nueva, el límite inicial es de 10 por minuto. Reduce la frecuencia de tus peticiones o espera a que se libere la cuota.
¿Se puede usar la SDK de OpenAI?
Sí, las SDK oficiales de OpenAI funcionan perfectamente. Solo necesitas cambiar la variable base_url a https://api.tk999us.info/v1 y usar tu clave API. Esto permite reutilizar el código existente sin modificar la lógica de integración principal.
¿Qué pasa si no se especifica el idioma?
El sistema intenta adivinar el idioma basado en el script del texto. Para texto en latín que no sea inglés, debes especificar explícitamente el código ISO del idioma para evitar errores de pronunciación y asegurar la claridad en la síntesis.
¿Es necesario usar HTTPS?
Sí, se recomienda HTTPS para la transmisión segura de datos y claves API.
¿Cuántas claves API puedo tener?
Cuenta con una clave activa por cuenta. Puedes emitir una nueva clave en cualquier momento desde tu panel. Al generar una nueva, la clave anterior deja de funcionar inmediatamente, garantizando un control preciso sobre el acceso a tu servicio.
¿Cómo se revoca una clave API?
La revocación es automática al emitir una nueva clave. Simplemente genera una nueva clave desde tu cuenta; la anterior dejará de funcionar al instante. Esto elimina la necesidad de esperar o realizar pasos adicionales para invalidar credenciales comprometidas.
Primera solicitud
curl
curl https://api.tk999us.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.tk999us.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.tk999us.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
La integración comienza con la obtención de la clave API en la página /get-api-key/. Regístrate con Google o correo electrónico para generar tu identificador único. Esta clave es el único mecanismo de autenticación necesario para todas las solicitudes a la API de VozRápida.
Obtención de clave API
Accede a /get-api-key/ tras crear tu cuenta. El sistema asigna automáticamente una clave activa y un saldo inicial (prueba gratuita de $0.50 si usas Google, de lo contrario sin crédito). Copia la clave que comienza con 'tts-...' para usarla en tus solicitudes.
Cabecera Authorization Bearer
Incluye la cabecera HTTP Authorization: Bearer tts-tu_clave_aqui en cada solicitud POST al endpoint /v1/audio/speech. Asegúrate de que la clave no contenga espacios extra ni saltos de línea. Si la clave es inválida, la API devolverá un error 401.
Gestión de claves activas
Cada cuenta solo tiene una clave activa a la vez. Si generas una nueva desde el panel, la anterior deja de funcionar inmediatamente. Esto elimina la necesidad de gestionar rotaciones complejas en sistemas IVR de alto volumen.
Endpoint principal de síntesis
El endpoint principal de VozRápida procesa la conversión de texto a audio mediante una única llamada HTTP. La API expone POST https://api.tk999us.info/v1/audio/speech para recibir texto y devolver el archivo de audio sintetizado en formato binario.
Esta ruta es compatible con la estructura de la API de OpenAI, lo que permite integrar la solución en sistemas IVR y centros de llamada sin necesidad de librerías propietarias adicionales.
Método POST /v1/audio/speech
Envía una solicitud POST con cabecera Authorization: Bearer <tu-clave> al endpoint especificado. La API devuelve el archivo de audio directamente en el cuerpo de la respuesta.
Cuerpo JSON de la solicitud
El cuerpo de la petición debe contener los campos requeridos para la síntesis. Asegúrate de que el texto no exceda los 4096 caracteres por solicitud.
model: "tts-1" o "tts-1-hd"input: El texto a sintetizarvoice: Identificador de la vozresponse_format: Formato de salida
Parámetros model e input
El parámetro model selecciona la calidad del motor de síntesis. El campo input acepta hasta 4096 caracteres, incluyendo espacios y puntuación, que se facturan como caracteres consumidos.
Uso con SDK de OpenAI
La API de VozRápida mantiene la misma forma de solicitud que el endpoint de speech de OpenAI. Esto permite reutilizar las librerías oficiales sin modificar la lógica de negocio, solo ajustando la configuración de conexión.
Cambio de base_url
Configura la variable de entorno OPENAI_BASE_URL o establece manualmente el atributo base_url del cliente a https://api.tk999us.info/v1. La autenticación sigue requiriendo la cabecera Authorization: Bearer con tu clave única.
Compatibilidad con librerías oficiales
Las librerías oficiales de OpenAI (Python, Node.js, etc.) funcionan correctamente. Solo necesitas asegurarte de que la versión de la librería soporte la estructura de parámetros model, input y voice.
- Compatible con
openaipara Python - Compatible con
openai-node - No requiere SDK propio de VozRápida
Ejemplo de código Python
Inicializa el cliente con la base URL personalizada y tu clave API. Luego, invoca la generación de audio con los parámetros estándar. El resultado se obtiene como un archivo de audio binario.
- Usar
import ospara cargar la clave - Establecer
base_urlexplícitamente - Manejar la respuesta como archivo binario
Formatos de audio soportados
La API devuelve audio completo tras la síntesis; no hay streaming ni fragmentos parciales en tiempo real. La elección del formato depende del equilibrio entre tamaño de archivo y calidad requerida por el sistema IVR o centro de llamada.
MP3 para streaming ligero
El formato MP3 es una opción estándar para reducir el tamaño del archivo. No se ofrece streaming ni audio parcial en tiempo real; se recibe el archivo completo tras la síntesis.
WAV para alta fidelidad
El formato WAV ofrece audio sin compresión, preservando la fidelidad original de la voz sintetizada. Es ideal para sistemas que priorizan la calidad sobre el ancho de banda.
OPUS y FLAC para compresión
OPUS ofrece una compresión eficiente, mientras que FLAC conserva la calidad lossless. El tamaño de archivo de FLAC suele ser mayor que el de MP3 o OPUS.
Parámetros de voz y velocidad
La API ofrece 8 voces predefinidas con tonos distintos, desde narrador claro hasta documental profundo. Cada voz puede hablar cualquiera de los 23 idiomas soportados, lo que permite flexibilidad en la generación de audio para IVR sin necesidad de múltiples modelos.
Selección de 8 voces
El campo voice acepta valores como aria, nova, luna, sage, felix, milo, atlas y orion. Estas voces están basadas en grabaciones con licencia y son suficientes para la mayoría de casos de uso en centros de llamada.
Rango de velocidad 0.25 a 4.0
Ajusta la velocidad de habla con el parámetro speed. Valores menores a 1.0 ralentizan la síntesis, mientras que valores mayores la aceleran. Esto es útil para adaptar el tiempo de respuesta en sistemas de voz interactiva.
Parámetro language opcional
El campo language acepta códigos ISO opcionales. Si no se especifica, el idioma se infiere del script (por defecto inglés para texto en latín). Configúralo explícitamente para textos en español u otros idiomas soportados para evitar errores de pronunciación.
- Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.

Límites y errores comunes
La API está diseñada para integraciones rápidas en centros de llamada y sistemas IVR, donde la previsibilidad del rendimiento es crítica. Conocer los límites técnicos permite evitar interrupciones en la generación de audio durante picos de tráfico o en la fase inicial de la cuenta.
Los errores no detienen la facturación; las solicitudes fallidas se devuelven íntegramente. Sin embargo, gestionar correctamente los límites de entrada y de tasa asegura que el audio se genere en tiempo real sin colas excesivas.
Límite de 4096 caracteres
Cada solicitud solo acepta hasta 4096 caracteres de texto. Si el guion de su IVR es más largo, debe dividirlo en fragmentos y concatenar los archivos de audio resultantes.
Los espacios y la puntuación cuentan como caracteres. El sistema no realiza división automática; la lógica de chunking debe implementarse en el lado del cliente para garantizar la fluidez de la voz.
- Máximo 4096 caracteres por POST /v1/audio/speech.
- Espacios y puntuación cuentan como caracteres.
- Divida textos largos antes de enviar la solicitud.
Código de estado 429
El código 429 indica que se ha excedido la cuota de 60 solicitudes por minuto por clave API (10 por minuto antes del primer recargo). Implemente backoff exponencial para reintentar automáticamente sin saturar la cola de procesamiento.
Este límite es por clave y se aplica globalmente. Si utiliza múltiples claves, distribuya la carga para respetar los 60 requests por minuto por cada una.
- Límite estándar: 60 requests/minuto por clave.
- Límite inicial: 10 requests/minuto sin recargo.
- Use backoff exponencial para reintentos.
Manejo de errores HTTP
Los errores de sintaxis o autenticación (4xx) no generan cargos. Si la síntesis falla, la carga se devuelve íntegramente.
Verifique siempre el código de estado antes de interpretar la respuesta. Un 200 indica éxito y contiene el archivo de audio binario o la URL de descarga según el formato solicitado.
- Errores 4xx: gratis, sin cargo.
- Éxito: código 200 con audio.
- Reintente en caso de 429 con backoff.
Manejo de textos largos
La API limita cada solicitud a 4096 caracteres. Si tu guion de IVR excede este límite, debes dividirlo manualmente o mediante código antes de enviar las peticiones.
División en partes de 4096 chars
Calcula la longitud del texto antes de enviarlo. Divide el guion en bloques que no superen los 4096 caracteres. Cada bloque genera un archivo de audio independiente.
Concatenación de archivos audio
La API no une los segmentos automáticamente. Recibe cada archivo por separado y únelos en tu servidor o aplicación cliente para crear el audio final continuo del IVR.
Estrategia de chunking
Divide en oraciones completas para evitar cortes abruptos en la voz. Usa el parámetro speed para ajustar la duración total si es necesario. Mantén la coherencia del mensaje.
- Procesa las solicitudes en secuencia para respetar el orden del guion.
Ejemplo completo con cURL
Este ejemplo demuestra la integración directa mediante cURL, ideal para pruebas rápidas en scripts de automatización IVR. Utiliza la clave API obtenida en la sección anterior y el endpoint estándar de síntesis.
La solicitud envía un texto corto en español y recibe un archivo MP3 binario. Este flujo es reproducible en cualquier entorno de desarrollo que soporte HTTP POST.
Comando de terminal listo
Ejecuta el siguiente comando reemplazando <TU_API_KEY> con tu credencial activa. El cuerpo JSON define el modelo tts-1, la voz nova y el idioma es explícitamente para evitar inferencias.
Visualización de respuesta
Si la solicitud es válida, el servidor devuelve el código de estado 200 OK junto con el archivo de audio en el cuerpo de la respuesta. No se devuelve JSON; el stream contiene directamente los bytes del audio.
Descarga del archivo resultante
Para guardar el audio localmente, redirige la salida a un archivo .mp3. Este archivo puede ser consumido inmediatamente por tu sistema IVR o centro de llamadas sin necesidad de procesamiento adicional.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Cada formato tiene implicaciones distintas en el consumo de ancho de banda y la compatibilidad con los reproductores de los sistemas de llamada.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
