Preguntas frecuentes
¿Qué es una API de texto a voz?
Es un servicio cloud que convierte texto en audio mediante una solicitud POST a /v1/audio/speech. Envías un JSON con el texto, el modelo (tts-1 o tts-1-hd) y la voz deseada, y recibes un archivo de audio. Es compatible con los SDKs oficiales de OpenAI cambiando la base_url a https://api.99bdcasino.com/v1, facilitando la integración en tus aplicaciones.
¿Cómo elijo la voz correcta para mi chatbot?
Elige entre 8 presets según el tono: femeninas (aria, nova, luna, sage) o masculinas (felix, milo, atlas, orion). Cada voz tiene un estilo específico, como narrador, energético o documental. Puedes probarlas en /v1/voices. Todas hablan los 23 idiomas soportados, ajustando el parámetro 'language' si es necesario.
¿Qué formato de audio es mejor para la web?
Para la web, mp3 u opus son ideales por su equilibrio entre calidad y tamaño. También puedes usar wav, flac o pcm según tus necesidades técnicas. El formato se especifica en el campo 'response_format' de tu solicitud. Estos formatos son estándar y ampliamente compatibles con reproductores de audio en navegadores y aplicaciones.
¿Cómo manejo textos que superan 4096 caracteres?
Debes dividir el texto en partes de máximo 4096 caracteres cada una. Realiza una solicitud POST para cada fragmento. Luego, une los archivos de audio resultantes en tu aplicación. Esto asegura que cada solicitud cumpla con el límite de longitud y genere el audio completo sin errores de truncamiento.
¿Es necesario un backend para la API?
No es estrictamente necesario, pero es recomendable para proteger tu clave API. Puedes llamar directamente desde el frontend si usas un proxy o gestionas los límites de seguridad adecuadamente. La API es RESTful y simple, pero usar un backend añade una capa de seguridad para evitar el uso excesivo de tu clave.
¿Puedo cambiar la velocidad de la voz?
Sí, puedes ajustar la velocidad entre 0.25 y 4.0 usando el parámetro 'speed'. Esto permite acelerar o ralentizar la voz del chatbot según el contexto. Ajustar la velocidad puede mejorar la experiencia del usuario, haciendo la conversación más dinámica o más pausada, según las necesidades de tu aplicación.
¿Qué hago si la API está lenta?
Las solicitudes se procesan en cola. Si hay alta demanda, puede haber retrasos. La velocidad típica es de unos 25 caracteres por segundo. Si la API está lenta, verifica tu tasa de solicitudes (límite de 60 por minuto) y considera dividir textos largos en múltiples solicitudes más pequeñas.
¿Cómo evito que se cueden caracteres?
El límite es de 4096 caracteres por solicitud. Si excedes este límite, la solicitud fallará. Divide tu texto en fragmentos más pequeños antes de enviarlos. Cada fragmento generará un archivo de audio que podrás unir posteriormente. Esto asegura que cada solicitud sea procesada correctamente sin errores por longitud.
¿Es seguro usar la API en el frontend?
Es posible, pero expone tu clave API. Para mayor seguridad, usa un backend intermedio que gestione las solicitudes. La clave se envía en el encabezado 'Authorization: Bearer tts-...'. Si la usas en frontend, considera implementar restricciones de origen (CORS) y límites de uso para proteger tu cuenta.
¿Qué idiomas puedo usar en el chatbot?
Soportamos 23 idiomas: árabe, chino, danés, neerlandés, inglés, finlandés, francés, alemán, griego, hebreo, hindi, italiano, japonés, coreano, malayo, noruego, polaco, portugués, ruso, español, swahili, sueco y turco. Si no especificas 'language', se asume inglés para texto en latín. Define el idioma explícitamente para textos en otros alfabetos.
¿Cómo se mide el costo por conversación?
El costo es de $10 por millón de caracteres, incluyendo espacios y puntuación. Cada solicitud cuenta los caracteres del texto enviado. Si la síntesis falla, el cargo se devuelve. Calcula el costo estimando los caracteres totales que tu chatbot procesará por conversación y multiplica por la tarifa por mil caracteres.
¿Puedo usar esta API para IVR telefónico?
Sí, es ideal para IVR. Genera archivos de audio claros y naturales que puedes almacenar o reproducir en tiempo real. Soporta formatos como wav y mp3, compatibles con sistemas telefónicos. Ajusta la velocidad y voz para adaptarse al tono de tu marca. No se ofrece clonación de voz personalizada. Es una solución económica y sencilla de integrar.
¿Qué pasa si se cae la conexión durante la carga?
Si la solicitud falla, el cargo se devuelve en su totalidad. El audio se devuelve en la respuesta. Si la conexión se pierde durante la descarga, simplemente reintenta la solicitud. La API no almacena el audio generado, por lo que debes guardarlo localmente si lo necesitas. Los errores devuelven el cargo si la síntesis fue exitosa.
¿Cómo pruebo la API antes de pagar?
Regístrate con Google y obtén $0.50 de crédito de prueba (válido 7 días). Esto equivale a unos 50 000 caracteres. Usa la clave API proporcionada en /get-api-key/ para realizar solicitudes. Si usas email y contraseña, no recibes crédito inicial. Prueba con textos cortos para verificar la calidad y el flujo.
Paso 1: Obtener la credencial API
Aquí comienza tu integración paso a paso para conectar VozBot API con tu chatbot. El primer bloque técnico es obtener la credencial que autoriza tus solicitudes.
Accede a /get-api-key/ desde 99bdcasino.com para registrarte con Google o correo electrónico. La plataforma genera una clave Bearer única para tu cuenta.
Registro en la plataforma
Visita la página de registro y elige iniciar sesión con Google o usar correo y contraseña. Las cuentas son independientes por sitio. Si usas Google, recibirás $0.50 de crédito válido por 7 días para probar.
Una vez registrado, el panel muestra tu clave API activa, el saldo disponible y un ejemplo de curl listo para usar. No necesitas configurar facturas ni suscripciones mensuales.
Ubicación de la clave Bearer
La clave tiene el formato 'tts-...' y se muestra en el panel de control tras el inicio de sesión. Úsala en el encabezado Authorization: Bearer <tu_clave> de cada petición POST.
Cada cuenta tiene una clave activa. Si emites una nueva, la anterior deja de funcionar inmediatamente. Puedes rotar la clave cuando quieras desde la misma sección.
- Formato: Bearer tts-...
Seguridad de la clave en el servidor
Almacena la clave en variables de entorno en tu backend, no en el código cliente visible. Esto evita que usuarios externos la extraigan y consuman tu saldo.
Como la clave es única por cuenta, su exposición directa impacta tu facturación. Usa el panel para verificar el uso y emitir una nueva si detectas actividad inusual.
Paso 2: Preparar la solicitud JSON
Paso 2: Preparar la solicitud JSON
Estructura del cuerpo de la petición
Envía un objeto JSON con campos requeridos como input (texto, máx. 4096 caracteres), voice y model. El cuerpo es idéntico al estándar de OpenAI, facilitando el uso de SDKs oficiales.
Los formatos de salida aceptados son mp3, wav, opus, flac y pcm. Ajusta el campo speed entre 0.25 y 4.0 para adaptar la velocidad a la interacción del chatbot.
Selección de la voz adecuada
- aria: narradora clara y cálida
- nova: brillante y animada
- luna: suave para historias
- sage: calma e instructiva
- felix: enérgica y promocional
- milo: amigable y conversacional
- atlas: neutral y noticiosa
- orion: profunda para documentales
Definición del modelo de audio
Selecciona tts-1 o tts-1-hd. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio por carácter ($0.01 por 1.000 caracteres).
- No hay diferencia de calidad audible garantizada entre ambos modelos, solo el formato de codificación.

Paso 3: Enviar la solicitud POST
Una vez configurada la estructura de la petición, el siguiente paso crítico es ejecutar la solicitud HTTP hacia nuestro servicio. Es fundamental garantizar que la conexión sea segura y que los encabezados de autenticación se transmitan correctamente para evitar rechazos inmediatos.
Este proceso implica enviar el texto a sintetizar y recibir el archivo de audio binario. La eficiencia en esta etapa determina la fluidez de la experiencia del usuario en el chatbot, especialmente cuando se manejan respuestas rápidas o interacciones en tiempo real.
Endpoint de la API
Dirige tu petición POST a https://api.99bdcasino.com/v1/audio/speech. Este es el único punto de entrada para la síntesis de voz. Asegúrate de que tu cliente HTTP esté configurado para manejar respuestas binarias directamente sin intentar parsearlas como JSON.
El endpoint acepta el cuerpo JSON con los parámetros definidos en el paso anterior. Si la ruta es incorrecta, recibirás un error 404. No se requiere autenticación adicional más allá del token en los encabezados.
- Método: POST
- URL:
https://api.99bdcasino.com/v1/audio/speech - Formato de entrada: JSON
- Formato de salida: Audio binario
Headers de autenticación
Incluye el encabezado Authorization: Bearer tts-TU_CLAVE_AQUI en cada solicitud. Esta clave única identifica tu cuenta y permite el cobro por los caracteres generados. Si omites este encabezado o la clave es inválida, la API devolverá un error 401.
Es recomendable que esta clave se almacene en variables de entorno en tu servidor backend y no se exponga directamente en el código del cliente del chatbot para mantener la seguridad de tu cuenta y saldo.
- Clave:
Authorization: Bearer tts-... - Ubicación: Header HTTP
- Formato: Bearer token
- Vigencia: Hasta rotación
Manejo de la respuesta binaria
La API devuelve el archivo de audio directamente en el cuerpo de la respuesta con el formato solicitado (mp3, wav, opus, flac, pcm). No hay un wrapper JSON; debes guardar o reproducir los bytes recibidos inmediatamente.
Si la solicitud es correcta, recibirás el código de estado 200 junto con el audio. En caso de error, recibirás un código de estado HTTP correspondiente (como 400 o 429) y una descripción breve en formato JSON explicando el fallo.
- Código de éxito: 200
- Tipos: mp3, wav, opus, flac, pcm
- Sin wrapper JSON en éxito
- Errores en JSON con código HTTP
Paso 4: Reproducir el audio en el cliente
La respuesta de la API devuelve el archivo de audio binario, listo para ser integrado directamente en la interfaz de usuario de tu chatbot. Utiliza la etiqueta HTML <audio> para reproducir el contenido. Algunos formatos como OPUS o FLAC pueden requerir codecs adicionales en ciertos navegadores.
Configura los atributos de control para permitir que el usuario gestione la reproducción manualmente o activa la reproducción automática mediante JavaScript, asegurando una experiencia fluida en asistentes de voz.
Uso de etiquetas <audio> HTML
Incorpora la etiqueta <audio> en el DOM de tu aplicación web para renderizar el audio recibido. Asigna la URL del archivo o los datos binarios al atributo 'src' y activa los controles nativos del navegador para pausar, detener o ajustar el volumen.
- Define atributos como 'controls' para facilitar la interacción del usuario.
- Asocia el src con la respuesta binaria de la API.
Reproducción automática o por clic
Dependiendo del flujo del chatbot, puedes invocar el método .play() tras recibir la respuesta o requerir un clic del usuario para iniciar la reproducción. Esto evita interrupciones no deseadas y mejora la usabilidad en dispositivos móviles.
Formatos compatibles con navegadores
Elige MP3 o WAV para una máxima compatibilidad con todos los navegadores modernos. Si optas por OPUS o FLAC, verifica que el cliente de destino los soporte para garantizar una reproducción sin errores.
Paso 5: Manejo de errores en tiempo real
La generación de audio puede tardar unos segundos en frases cortas o colarse bajo carga. No asumas que la respuesta es instantánea.
Si la API falla o devuelve un error, no detengas la conversación. Muestra el texto como respaldo y notifica al usuario que se procesa.
Retrasos en la generación
Las solicitudes se procesan en cola. Si hay alta demanda, espera más tiempo. No muestres un spinner infinito sin límite.
Fallback a texto si falla el audio
Si la síntesis falla, el cargo se devuelve. Muestra el texto del chatbot inmediatamente para mantener la fluidez.
Notificaciones de estado al usuario
Informa claramente cuando el audio está listo o si hay un error transitorio. Usa indicadores visuales simples.
Paso 6: Optimización para chatbots
Optimizar la integración de VozBot API en chatbots reduce la latencia percibida y el consumo de caracteres. Al anticipar las respuestas más comunes, puedes evitar llamadas a la API en tiempo real para frases recurrentes.
Estas técnicas permiten que el asistente de voz mantenga una conversación fluida, incluso si el usuario experimenta pequeños retrasos en la generación de audio debido a la cola de procesamiento.
Caché de respuestas frecuentes
Almacena los archivos de audio generados (mp3, wav, opus, flac, pcm) en tu servidor para las preguntas más habituales. Esto elimina la necesidad de solicitar síntesis repetida y ahorra caracteres en tu saldo.
Verifica el hash del texto para garantizar que la versión caché sigue siendo válida si cambias la voz o el modelo.
- Almacena hashes MD5/SHA del texto de entrada.
- Asocia cada hash al archivo de audio generado.
- Invalida la caché si cambias el modelo o la voz.
Precarga de audios comunes
Genera y descarga anticipadamente los audios para saludos, despedidas y frases de espera. Esto asegura que el usuario escuche audio inmediatamente sin esperar la generación.
Ideal para iniciar la conversación o mantener el engagement mientras se procesan respuestas más complejas en segundo plano.
- Saludos iniciales y despedidas.
- Frase de 'procesando...'.
- Confirmaciones de éxito o error.
Uso de velocidades aceleradas
Ajusta el parámetro speed entre 0.25 y 4.0 para reducir el tiempo de generación y la duración del audio. Esto es útil para respuestas cortas donde la naturalidad no es crítica.
Recuerda que velocidades superiores a 1.0 pueden alterar la claridad, por lo que prueba con la voz 'nova' o 'felix' para mantener la energía.
- Velocidad recomendada: 1.2x - 1.5x para respuestas rápidas.
- Monitorea la claridad con diferentes voces.
- Ajusta dinámicamente según la longitud del texto.
Paso 7: Manejo de textos largos
Los textos excedentes se dividen en fragmentos de hasta 4096 caracteres. Cada parte se sintetiza por separado mediante solicitudes POST consecutivas.
Los archivos de audio resultantes se concatenan para formar la respuesta final. Este proceso permite gestionar narrativas extensas sin límites rígidos de entrada.
División en fragmentos < 4096 chars
Envía el texto completo a tu lógica de división antes de llamar a la API. Cada solicitud debe contener menos de 4096 caracteres para evitar errores de formato.
Calcula los caracteres incluyendo espacios y puntuación. Esto asegura que el límite se respete exactamente y no haya sorpresas al generar.
- Límite estricto de 4096 caracteres por petición.
- Incluye espacios y puntuación en el conteo.
Concatenación de archivos de audio
Recibe cada fragmento de audio como un archivo binario. Une estos archivos en el orden correcto para mantener la coherencia del discurso.
El cliente o backend debe manejar la unión sin introducir silencios adicionales. El resultado es un archivo continuo listo para reproducir.
Esta estrategia evita la pérdida de contexto al mantener la fluidez natural de la voz sintética.
- Mantén el orden secuencial de los fragmentos.
- Evita silencios entre uniones si es posible.
Control de tiempos de espera
La generación es aproximadamente en tiempo real (25 caracteres por segundo). Para textos largos, espera varios segundos.
Ajusta el tiempo de espera de tu aplicación según la longitud total. Un límite bajo podría cortar la síntesis antes de completarse.
Considera la cola de procesamiento bajo carga. Los tiempos pueden variar ligeramente durante picos de demanda.
- Tiempo estimado: ~25 caracteres por segundo.
- Ajusta timeouts según longitud total del texto.

Paso 8: Configuración de idioma
Configurar el idioma correctamente evita que la voz suene extraña al pronunciar palabras en otro idioma. La API detecta automáticamente el idioma basándose en los caracteres del texto, asumiendo inglés por defecto si usa el alfabeto latino.
Sin embargo, esta detección no es infalible. Si tu chatbot maneja frases cortas o mezcladas, es mejor especificar el idioma explícitamente para garantizar una pronunciación natural y precisa.
Uso del parámetro 'language'
Incluye el código ISO del idioma (por ejemplo, 'es' para español, 'fr' para francés) en el cuerpo de la solicitud JSON. Esto asegura que la voz utilice las reglas fonéticas correctas desde el primer carácter.
Detección automática y sus límites
Si omites el parámetro, el sistema infiere el idioma. Esto funciona bien para textos largos y coherentes, pero puede fallar con frases muy breves o nombres propios que se confunden con otro idioma.
Forzar idioma para textos ambiguos
Para textos en latín que no son inglés, o frases cortas ambiguas, establece siempre el campo 'language'. Esto elimina suposiciones y garantiza que la síntesis sea predecible y natural para el usuario final.
Paso 9: Pruebas y depuración
Verificar que el conteo de caracteres sea preciso es fundamental para controlar los costos y evitar errores de límite. Recuerde que los espacios y la puntuación se cuentan como caracteres individuales; un texto de 4096 caracteres es el máximo permitido por solicitud. Utilice la consola de desarrollo del navegador para inspeccionar la carga útil enviada y confirmar que el campo input coincida exactamente con el texto procesado.
La depuración efectiva requiere visibilidad en tiempo real. Monitoree las solicitudes HTTP para asegurar que la autenticación y los parámetros sean correctos. Esto ayuda a identificar rápidamente si el problema reside en la codificación del texto o en la estructura de la petición JSON antes de que se genere el audio.
Verificación de caracteres contados
Asegúrese de que el contador de caracteres en su código coincida con la lógica del servidor, ya que cada espacio y signo de puntuación cuenta. Esto previene errores de límite y permite una estimación precisa del costo, dado que el precio es de $0.01 por cada 1.000 caracteres.
- Los espacios y la puntuación se cuentan como caracteres individuales.
- El límite máximo es de 4096 caracteres por solicitud.
- Use funciones de longitud de cadena estándar en su lenguaje de programación.
Uso de la consola de red
Utilice la pestaña 'Network' de las herramientas de desarrollo del navegador para inspeccionar la solicitud POST. Verifique que el encabezado Authorization contenga la clave correcta y que el cuerpo JSON esté bien formado. Esto facilita la identificación de errores de sintaxis o problemas de conexión.
Observe los tiempos de respuesta para detectar si la solicitud está en cola, especialmente bajo carga. Esto ayuda a ajustar la experiencia del usuario sin necesidad de implementar lógica compleja de reintentos.
- Inspeccione la pestaña Network para ver la petición completa.
- Verifique el encabezado Authorization y el cuerpo JSON.
- Monitoree el tiempo de espera para identificar colas de procesamiento.
Validación de formatos de salida
Pruebe los diferentes formatos de respuesta (mp3, wav, opus, flac, pcm) para asegurar que son compatibles con el cliente final. El formato mp3 es ampliamente soportado, pero otros como opus pueden requerir codecs adicionales en algunos navegadores o aplicaciones.
Confirmar que el audio se reproduce correctamente en el entorno de prueba asegura que la integración esté lista para el despliegue en producción sin sorpresas con formatos no soportados.
- Pruebe mp3, wav, opus, flac y pcm.
- Verifique la compatibilidad con el cliente final.
- Asegúrese de que los codecs necesarios estén instalados.
Paso 10: Despliegue en producción
El despliegue en producción requiere monitorizar el consumo de caracteres para anticipar la necesidad de recargas. Dado que el costo es de $0.01 por 1.000 caracteres, el saldo debe verificarse regularmente para evitar interrupciones en el servicio del chatbot.
Monitoreo del consumo de caracteres
Registra el uso acumulado en el panel de la plataforma. La API no almacena audio generado, por lo que el historial de facturación se basa en metadatos de la solicitud (tiempo, caracteres, estado).
Establece alertas cuando el saldo se acerque al mínimo, especialmente si no se usan recargas automáticas con USDT.
- Verificar el saldo en /get-api-key/ antes de picos de tráfico
- Registrar caracteres enviados por sesión de chat
Gestión de límites de tasa
El límite estándar es de 60 solicitudes por minuto por clave. Si superas este umbral, las peticiones se encolarán o fallarán.
Antes de la primera recarga, el límite es de 10 solicitudes por minuto. Aumenta la capacidad tras añadir saldo vía TRC-20.
- Implementar reintentos con backoff exponencial
- Monitorizar respuestas 429 Too Many Requests
Escalado según demanda
Para alta demanda, considera emitir una nueva clave y usar ambas en paralelo, ya que los límites son por clave.
No hay planes por asiento ni SLA, por lo que la escalabilidad depende de tu gestión de colas y del tiempo de generación (aprox. 25 caracteres/segundo en textos largos).
Paso 11: Seguridad y claves
La API Key es el único elemento que autentifica tu servicio. Debe protegerse como si fuera una contraseña crítica, ya que quien la posea podrá consumir tu saldo de caracteres. No la expongas en el código del cliente (frontend) ni en repositorios públicos.
Mantén la clave aislada en tu entorno de servidor. Esto evita que usuarios externos puedan interceptarla y generar audio a tu costa sin que lo notes inmediatamente.
Almacenamiento seguro de la API Key
Almacena la clave en variables de entorno de tu servidor de backend, no en el código fuente visible. Esto asegura que solo tu aplicación pueda acceder a ella durante la generación de audio.
Utiliza servicios de gestión de secretos si tu infraestructura lo permite. La clave debe estar disponible para el proceso que ejecuta las llamadas a la API, pero oculta a otros procesos.
- Nunca compartas la clave por correo o chat sin encriptación.
- Verifica que no aparezca en logs públicos o archivos de configuración expuestos.
Rotación de claves periódica
Puedes emitir una nueva clave en cualquier momento desde tu panel de control. Al generar la nueva, la clave anterior deja de funcionar inmediatamente.
Esto es útil si sospechas que una clave ha sido comprometida o si cambias de servidor. El cambio es instantáneo y no requiere reinicios.
- Genera una nueva clave cuando haya sospecha de uso indebido.
- La rotación no afecta el saldo ni la configuración de tu cuenta.
Uso de variables de entorno
Configura la variable de entorno en tu servidor de despliegue. La mayoría de los frameworks modernos permiten leerla automáticamente al iniciar la aplicación.
Esto facilita el despliegue en diferentes entornos (desarrollo, producción) sin modificar el código de tu chatbot.
- Usa variables como
VOZBOT_API_KEYen tu configuración. - Asegúrate de que el servidor de producción tenga acceso a estas variables.

Paso 12: Soporte y problemas comunes
El soporte técnico de VozBot API se gestiona exclusivamente por correo electrónico, ya que no disponemos de chat en vivo ni número de teléfono directo. Esta vía permite atender incidencias con precisión técnica sin distracciones.
Para resolver problemas comunes, verificamos primero los límites de tasa y el saldo disponible, dos factores críticos en la integración de chatbots.
Contacto por correo electrónico
Envía tu consulta a [email protected] incluyendo tu ID de cuenta y el código de error si lo hay. Nuestro equipo responde por escrito para mantener un registro claro de la incidencia.
Soluciones a errores 429
El error 429 indica que has alcanzado el límite de 60 solicitudes por minuto. Implementa una lógica de reintentos con backoff exponencial o reduce la velocidad de generación para respetar el umbral.
- Espera 1-2 segundos antes de reintentar.
- Monitorea el encabezado
X-RateLimit-Remainingsi está disponible.
Verificación de saldos disponibles
Consulta tu saldo en /get-api-key/ o mediante la API. Si el saldo es insuficiente, las solicitudes fallarán. Recuerda que las recargas en USDT (TRC-20) se acreditan en minutos.
- El saldo no tiene fecha de expiración.
- La prueba gratuita de $0.50 vence en 7 días.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Nuestra IA entiende el contexto como un humano, ofreciendo respuestas precisas y fluidas.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
