Documentación técnica de la API de texto a voz

Por Equipo editorial de VozBot API · Actualizado 2026-11-18

Esta documentación técnica está diseñada para equipos de desarrollo de startups que integran voces naturales en asistentes de voz y chatbots. Aquí encontrarás los detalles precisos para conectar tu aplicación a la API de texto a voz mediante endpoints REST simples, sin dependencias de SDK propietarios ni complejidades innecesarias.

Obtendrás ejemplos concretos de autenticación, estructuras de JSON y código listo para copiar. La guía cubre la generación de audio, el manejo de límites de tasa y la integración con SDKs compatibles con OpenAI, asegurando una implementación rápida y predecible para automatizar la síntesis de audio en tus productos.

Documentación técnica de la API de texto a voz

Preguntas frecuentes

¿Cómo obtengo mi API key?

Regístrate en /get-api-key/ con Google o email. La clave se muestra en tu panel de cuenta. Es única por cuenta y se usa en el encabezado Authorization: Bearer tts-... Puedes emitir una nueva clave en cualquier momento; la anterior deja de funcionar inmediatamente.

¿Qué es el endpoint POST /v1/audio/speech?

Es el punto final principal para enviar texto y recibir audio. Recibe un cuerpo JSON con campos como model, input, voice y response_format. Devuelve el archivo de audio generado directamente en la respuesta HTTP, listo para ser reproducido o almacenado por tu aplicación.

¿Puedo usar el SDK de Python de OpenAI?

Sí. El endpoint tiene la misma forma de solicitud que la API de OpenAI. Solo necesitas cambiar la base_url a https://api.99bdcasino.com/v1 y usar tu clave de VozBot API. Esto permite reutilizar el código existente del SDK oficial de OpenAI sin modificaciones mayores.

¿Qué formato de audio es mejor para chatbots?

Para chatbots, mp3 o opus son ideales por su equilibrio entre calidad y tamaño de archivo. El formato opus ofrece una compresión eficiente que reduce el ancho de banda. Puedes especificar el formato deseado en el campo response_format de tu solicitud JSON al endpoint de speech.

¿Cómo ajusto la velocidad de la voz?

Usa el campo speed en la solicitud JSON. El valor debe estar entre 0.25 y 4.0. Un valor de 1.0 es la velocidad normal. Ajustar este parámetro permite acelerar o ralentizar la voz sintética sin cambiar el tono o la entonación de la voz seleccionada.

¿Qué pasa si excedo los 4096 caracteres?

La API rechaza solicitudes con más de 4096 caracteres en el campo input. Debes dividir tu texto en partes más pequeñas antes de enviarlo. Cada parte generará un archivo de audio independiente que luego podrás unir en tu aplicación para crear el audio completo.

¿Cómo divido textos largos automáticamente?

Tu aplicación debe dividir el texto en fragmentos de máximo 4096 caracteres. Luego, envía cada fragmento en una solicitud POST independiente. Finalmente, une los archivos de audio resultantes en el orden original para reproducir el texto completo como una sola pista continua.

¿Qué códigos de error devolverá la API?

La API devuelve códigos HTTP estándar para indicar el estado de la solicitud. Por ejemplo, 400 para errores de entrada o 401 si la clave es inválida. Las solicitudes fallidas son gratuitas y el cargo se devuelve íntegramente si la síntesis no se completa correctamente.

¿Es necesario usar el modelo tts-1-hd para alta calidad?

No. Los modelos tts-1 y tts-1-hd utilizan el mismo motor y precio. La diferencia es solo el formato de audio resultante, no la calidad de la voz. Ambos tienen las mismas características.

¿Cómo cambio mi clave API si se compromete?

Emite una nueva clave desde tu panel de cuenta en /get-api-key/. La nueva clave se activa inmediatamente y la anterior deja de funcionar al instante. No necesitas esperar ni configurar nada más. Puedes generar nuevas claves tantas veces como necesites para mantener la seguridad.

¿Qué hace el endpoint GET /v1/models?

Este endpoint devuelve información sobre los modelos disponibles, como tts-1 y tts-1-hd. También proporciona detalles sobre las voces, idiomas y formatos de audio soportados (GET /v1/voices). Es útil para verificar la disponibilidad de recursos antes de realizar solicitudes de síntesis de voz a la API.

¿Puedo especificar el idioma manualmente?

Sí, usa el campo language con un código ISO. Si no se especifica, el sistema intenta adivinar el idioma basándose en el script, asumiendo inglés para texto en latín. Para textos en otros idiomas con script latino, establece el campo language explícitamente para evitar errores.

¿Cómo se mide el tiempo de respuesta?

La velocidad es aproximadamente en tiempo real para textos largos, generando unos 25 caracteres por segundo. Las frases cortas pueden tardar unos segundos. Las solicitudes se procesan en cola, por lo que bajo carga alta podría haber retrasos adicionales antes de comenzar la síntesis.

¿Hay un límite de tamaño para el archivo de audio final?

No hay un límite estricto de tamaño para el archivo final, pero cada solicitud está limitada a 4096 caracteres de entrada. Para textos más largos, debes dividirlos y unir los archivos resultantes. El tamaño final dependerá de la duración del texto y el formato seleccionado.

Primera solicitud

curl

curl https://api.99bdcasino.com/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.99bdcasino.com/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.99bdcasino.com/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 API Key

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

Obtén tu clave API registrándote en la página /get-api-key/ con Google o correo electrónico. Una vez registrado, la plataforma te proporciona una clave única y un saldo inicial para empezar a integrar voces naturales en tus chatbots sin complicaciones técnicas.

Utiliza esta clave para autenticar tus solicitudes mediante un Bearer Token en el encabezado Authorization. Si necesitas renovar la credencial por seguridad, emite una nueva clave directamente desde tu panel; la anterior dejará de funcionar inmediatamente.

Registro en /get-api-key/

Accede a /get-api-key/ para crear tu cuenta. Puedes usar tu cuenta de Google para un acceso inmediato o registrarte con correo y contraseña. Esta página centraliza tu clave, saldo y métricas de uso.

  • Registro rápido con Google o email
  • Visualización inmediata de la API Key

Autenticación con Bearer Token

Incluye el encabezado Authorization: Bearer tts-TU_CLAVE en cada solicitud POST. Esto garantiza que tu cuenta esté verificada y que los caracteres consumidos se descuenten correctamente de tu saldo.

Emisión de nuevas claves

Puedes generar una nueva clave en cualquier momento desde tu panel. Al emitir una nueva, la clave anterior queda inválada al instante, lo que es útil para revocar acceso rápidamente.

Endpoint principal: POST /v1/audio/speech

Ilustración de onda de sonido para: Endpoint principal: POST /v1/audio/speech

La generación de audio se realiza mediante una solicitud HTTP POST a https://api.99bdcasino.com/v1/audio/speech. El cuerpo de la petición debe contener el texto y los parámetros de configuración en formato JSON.

La API devuelve el archivo de audio directamente en la respuesta, listo para ser reproducido o almacenado en tu infraestructura de chatbots.

Estructura del cuerpo JSON

Envía un objeto JSON con las propiedades requeridas. La estructura sigue el estándar de los endpoints de audio de OpenAI, lo que facilita la integración en asistentes de voz existentes.

  • model
  • input
  • voice
  • response_format
  • speed

Parámetros: model, input, voice, speed

El parámetro input acepta hasta 4096 caracteres por solicitud. model puede ser 'tts-1' o 'tts-1-hd', ambos con el mismo motor y precio. voice debe ser uno de los 8 presets disponibles. speed varía entre 0.25 y 4.0.

Formato de respuesta con audio

La respuesta contiene el archivo de audio binario en el formato solicitado (mp3, wav, opus, flac o pcm). Los formatos lossless como FLAC o WAV son ideales para alta fidelidad, mientras que MP3 u OPUS optimizan el ancho de banda para transmisión.

Endpoint principal: POST /v1/audio/speech

Integración con SDK de OpenAI

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

Adaptar la integración de VozBot API con el SDK de OpenAI requiere modificar únicamente la URL base. Esta configuración permite reutilizar el código existente sin cambiar la lógica de llamadas, ideal para startups que buscan automatización rápida.

Al cambiar el base_url al punto final de la API, el SDK interpreta las solicitudes correctamente. Esto facilita la transición desde otros servicios sin necesidad de reescribir la lógica de generación de audio en asistentes de voz.

Modificación de base_url

Establezca base_url en https://api.99bdcasino.com/v1. Esta ruta dirige las solicitudes al motor de VozBot API, manteniendo la estructura de endpoints compatible con OpenAI. Solo requiere cambiar esta variable de entorno antes de inicializar el cliente.

  • URL base: https://api.99bdcasino.com/v1
  • Compatible con SDKs oficiales de OpenAI

Uso del mismo código que OpenAI

La estructura del cuerpo JSON es idéntica a la de OpenAI. Utilice los mismos métodos client.audio.speech.create con los parámetros model, input, voice y response_format. No se necesitan adaptadores adicionales ni librerías intermediarias.

Esta similitud permite probar integraciones con scripts estándar y escalar la generación de audio en chatbots sin reescribir la lógica de petición. El código se ejecuta directamente sobre la API de VozBot.

Configuración de headers

El SDK maneja automáticamente la autenticación si se proporciona la API Key en el header Authorization: Bearer <su_clave>. Asegúrese de que la clave esté activa y tenga saldo suficiente.

No es necesario modificar manualmente los encabezados HTTP estándar si se usa el cliente configurado. La gestión de la clave es única por cuenta y se emite desde /get-api-key/.

Voces y modelos disponibles

Ilustración de onda de sonido para: Voces y modelos disponibles

VozBot API ofrece 8 voces predefinidas, basadas en grabaciones licenciadas de LibriTTS-R y audiopublicos de LibriVox. Cada voz tiene un tono distintivo para adaptar el asistente de voz a la identidad de tu startup.

Los modelos tts-1 y tts-1-hd utilizan el mismo motor y precio. La diferencia radica únicamente en el formato de audio resultante, no en la calidad de la voz.

Lista de 8 voces con descripciones

Selecciona la voz que mejor se adapte a la interacción. Todas pueden hablar los 23 idiomas soportados; si no se especifica language, el sistema asume inglés para textos en latín.

Las voces incluyen: Aria (narradora clara), Nova (alegre), Luna (suave), Sage (instruccional), Felix (enérgico), Milo (conversacional), Atlas (neutral) y Orion (documental).

  • Aria: Narradora cálida y clara.
  • Nova: Voz brillante y animada.
  • Luna: Suave, ideal para historias.
  • Sage: Calma, tono instruccional.
  • Felix: Enérgico, ideal para promociones.
  • Milo: Amigable y conversacional.

Modelos tts-1 y tts-1-hd

Ambos modelos ofrecen la misma calidad de voz y precio ($0.01 por 1.000 caracteres). Utiliza tts-1 para optimizar costos o tts-1-hd para mayor fidelidad en la reproducción.

Endpoint GET /v1/voices

Consulta el endpoint GET /v1/voices para obtener la lista actualizada de voces, idiomas y formatos disponibles. Esta información es esencial para configurar correctamente las llamadas a la API de texto a voz.

Formatos de salida y velocidad

Ilustración de onda de sonido para: Formatos de salida y velocidad

La API permite recibir el audio generado en cinco formatos distintos: mp3, wav, opus, flac y pcm. Esta flexibilidad permite adaptar la entrega del archivo a las necesidades específicas del cliente, ya sea para optimización de espacio o para procesamiento posterior sin compresión.

Opciones: mp3, wav, opus, flac, pcm

El formato mp3 es ideal para la mayoría de las aplicaciones web y móviles debido a su equilibrio entre calidad y tamaño. Para integraciones que requieren audio sin pérdida, wav y flac ofrecen la máxima fidelidad. opus y pcm son opciones adicionales para casos de uso específicos donde se prioriza la eficiencia o la compatibilidad directa con reproductores de código abierto.

  • mp3: Compresión con pérdida, tamaño reducido.
  • wav: Sin compresión, estándar en audio digital.
  • opus: Alta eficiencia para web.
  • flac: Compresión sin pérdida de datos.
  • pcm: Audio crudo sin procesar.

Rango de velocidad: 0.25 a 4.0

Puedes ajustar la velocidad de generación entre 0.25 y 4.0 veces la velocidad normal. Un valor inferior a 1.0 ralentiza la voz, útil para audioguías o aprendizaje. Valores superiores a 1.0 aceleran la síntesis, permitiendo entregar más contenido en menos tiempo, lo que es útil para notificaciones rápidas o resúmenes de datos.

Selección según ancho de banda

La elección del formato y la velocidad impacta directamente en el consumo de ancho de banda. Usa opus o mp3 para minimizar el tráfico de red en entornos móviles o con conexiones limitadas. Reserva wav o flac para servidores internos o entornos de desarrollo donde el ancho de banda no es una restricción crítica y la integridad del audio es prioritaria.

Formatos de salida y velocidad

Límites y gestión de carga

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

Cada clave API tiene un límite de 60 solicitudes por minuto. Este umbral es estricto y se aplica por cuenta, no por IP. Si excedes el límite, la API devuelve un error 429 (Too Many Requests) hasta que el contador se reinicie.

Para aplicaciones que requieren alta concurrencia, considera distribuir las solicitudes o implementar reintentos con backoff exponencial. La monitorización del saldo y el uso en tiempo real desde /get-api-key/ ayuda a anticipar picos de tráfico.

60 solicitudes por minuto

El límite estándar permite 60 solicitudes por minuto por clave activa. Este valor es suficiente para la mayoría de las integraciones de chatbots con flujo de conversación natural. Las solicitudes fallidas no consumen cuota de caracteres, pero sí cuentan para el límite de tasa si ocurren dentro del intervalo.

  • Límite base: 60 req/min por clave.
  • Aplica por cuenta, no por dirección IP.
  • Los errores de formato no eximen del conteo de tasa.

10 solicitudes antes del primer pago

Al crear una cuenta nueva, el límite inicial se reduce a 10 solicitudes por minuto. Este umbral menor facilita la prueba inicial sin saturar la infraestructura. Tras la primera recarga de saldo, el límite se eleva automáticamente a los 60 req/min estándar.

  • Nuevo usuario: 10 req/min.
  • tras primer pago: 60 req/min.
  • El cambio es automático e instantáneo.

Manejo de colas bajo carga

Las solicitudes se procesan en orden de llegada. Si la cola se llena, la generación puede tardar más que el tiempo real. Para textos largos, se recomienda enviar fragmentos de máximo 4096 caracteres con un pequeño retraso entre ellos para evitar saturación.

  • Procesamiento secuencial bajo alta demanda.
  • Latencia mayor en picos de tráfico.
  • Fragmentación recomendada para textos >4096 chars.

Manejo de errores comunes

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

Los errores en la integración de VozBot API suelen deberse a credenciales inválidas, exceder los límites de velocidad o enviar textos con formato incorrecto. Comprender las respuestas HTTP específicas permite depurar rápidamente la conexión entre tu chatbot y el servicio de síntesis de voz.

En esta sección, detallamos los códigos de estado más comunes que recibirás durante las llamadas a la API y cómo resolverlos sin detener el flujo de tu asistente de voz.

Errores de autenticación (401)

Recibirás un error 401 si la clave API en el encabezado Authorization: Bearer es incorrecta, está expirada o no tiene permisos. Verifica que la clave comience con tts- y esté activa en tu panel de /get-api-key/.

Recuerda que solo hay una clave activa por cuenta. Si emites una nueva, la anterior deja de funcionar inmediatamente.

  • Verifica que el token no tenga espacios extra.
  • Asegúrate de que la clave esté generada y activa.

Límites de tasa excedidos (429)

El límite es de 60 solicitudes por minuto por clave. Si tu startup inicia sin top-up, el límite inicial es de 10 solicitudes por minuto. Exceder este límite devuelve un 429.

Las solicitudes se procesan en cola; bajo carga, la latencia aumenta aunque no hayas excedido el límite estricto.

  • Implementa backoff exponencial en tu cliente.
  • Monitorea el balance antes de lanzar lotes masivos.

Errores de formato de entrada

Si el texto excede los 4096 caracteres o el formato JSON es inválido, la API rechazará la solicitud. Asegúrate de que el campo input sea una cadena válida y que voice esté en la lista de 8 presets disponibles.

Los errores de formato suelen indicar campos faltantes o tipos de datos incorrectos en el cuerpo de la petición.

  • Valida la longitud del texto antes de enviarlo.
  • Verifica que el JSON esté bien formado.
Manejo de errores comunes

Ejemplo completo en cURL

Ilustración de onda de sonido para: Ejemplo completo en cURL

Aquí tienes un ejemplo concreto para generar audio mediante la API de VozBot. Este comando simula una solicitud real que puedes ejecutar directamente en tu terminal para verificar la integración.

El ejemplo utiliza parámetros básicos y devuelve el archivo de audio en formato MP3. Puedes adaptar los valores según tus necesidades específicas de latencia o calidad.

Comando listo para copiar

Ejecuta este comando reemplazando tu clave API. La solicitud envía un texto breve y devuelve el audio sintetizado.

  • curl -X POST https://api.99bdcasino.com/v1/audio/speech \
  • -H "Authorization: Bearer tts-tu_clave_aqui" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Hola, soy un asistente de voz.", "voice": "nova", "response_format": "mp3"}'

Uso de variables de entorno

Para evitar exponer tu clave en el historial de comandos, almacénala en una variable de entorno llamada TTS_KEY. Luego, referencia esta variable en el encabezado Authorization de tu solicitud cURL.

  • export TTS_KEY="tts-tu_clave_aqui"
  • curl -X POST https://api.99bdcasino.com/v1/audio/speech \
  • -H "Authorization: Bearer $TTS_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Texto de prueba", "voice": "nova", "response_format": "mp3"}'

Verificación de respuesta exitosa

Una respuesta correcta (200 OK) devuelve el archivo de audio binario en el cuerpo de la respuesta. Si el formato es MP3, puedes guardar el resultado en un archivo local con > audio.mp3.

  • Recibe un código de estado 200.
  • El cuerpo contiene datos binarios de audio.
  • Los errores comunes incluyen 401 (clave inválida) o 429 (límite excedido).

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.

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. curl documentation
  3. IETF RFC 7845: Ogg Opus
  4. ISO 639 language codes
  5. OpenAI API reference: create speech
  6. Creative Commons Attribution 4.0
  7. MDN: Web Speech API
  8. LibriVox public-domain audiobooks
  9. Python documentation
  10. openai-python on GitHub
  11. TRON developer hub: TRC-20
  12. W3C WAI: making audio and video accessible

Más en este sitio