Guía de integración y uso de la API de síntesis de voz

Por Equipo editorial de VozNativa · Actualizado 2026-11-19

Esta guía explica cómo integrar nuestra API de texto a voz en aplicaciones de aprendizaje de idiomas. Verás cómo obtener tu clave, enviar texto y recibir un archivo de audio, con tiempos de generación variables según la cola, con ejemplos listos para copiar y usar en tu proyecto.

Está pensada para desarrolladores de startups educativas que necesitan voces multilingües claras y naturales. Aquí encontrarás la referencia técnica completa de los endpoints, los parámetros de voz, los límites de uso y los formatos de audio compatibles.

Guía de integración y uso de la API de síntesis de voz

Preguntas frecuentes

¿Qué es un endpoint API?

El endpoint es la dirección URL donde envías tus solicitudes. Para esta API, usas POST https://api.11111bet.info/v1/audio/speech con un cuerpo JSON. También puedes consultar GET /v1/voices para ver las voces disponibles o GET /v1/models para los modelos. Es la puerta de entrada para generar audio desde texto mediante llamadas HTTP estándar.

¿Cómo se autentica la API?

Debes incluir tu clave en el encabezado de la solicitud: Authorization: Bearer tts-... Cada cuenta tiene una clave activa. Si emites una nueva, la anterior deja de funcionar inmediatamente. La clave se genera al registrarte en /get-api-key/ y se usa para autorizar todas las peticiones de síntesis de voz.

¿Qué formato de audio devuelve la API?

La API devuelve archivos de audio en los formatos mp3, wav, opus, flac o pcm. Puedes especificar el formato deseado en el campo response_format de tu solicitud JSON. Estos formatos son estándar y compatibles con la mayoría de reproductores y bibliotecas de audio utilizadas en aplicaciones móviles y web.

¿Puedo usar la librería de OpenAI?

Sí, la forma de solicitud es idéntica a la de OpenAI. Solo necesitas cambiar la base_url a https://api.11111bet.info/v1 y usar tu propia clave de API. Las librerías oficiales de OpenAI funcionarán directamente sin modificaciones adicionales en tu código, facilitando la integración en tus proyectos existentes.

¿Cuál es el límite de caracteres?

Cada solicitud puede contener hasta 4096 caracteres de texto. Si necesitas generar audio para textos más largos, debes dividirlos en partes de este tamaño y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres dentro de este límite por solicitud.

¿Qué pasa si excedo los 60 requests/min?

El límite es de 60 solicitudes por minuto por clave. Si excedes este límite, las solicitudes adicionales se procesarán una tras otra, lo que puede aumentar el tiempo de espera. Si tu cuenta es nueva, el límite inicial es de 10 solicitudes por minuto hasta que realices tu primera recarga.

¿Cómo cambio la velocidad de la voz?

Puedes ajustar la velocidad usando el campo speed en tu solicitud JSON. El valor debe estar entre 0.25 y 4.0, donde 1.0 es la velocidad normal. Esto te permite hacer la voz más lenta para fines educativos o más rápida para resúmenes, adaptándola a la experiencia de usuario.

¿Qué es la API Key?

Es tu credencial única que autoriza el uso de la API. Se genera al registrarte en la página /get-api-key/. Puedes emitir una nueva clave en cualquier momento, lo que invalida inmediatamente la anterior. Se usa en el encabezado de autorización para identificar tu cuenta y facturar el consumo.

¿Se puede usar con Python?

Sí, puedes usar cualquier lenguaje que soporte solicitudes HTTP o las librerías de OpenAI. En Python, simplemente configura la base_url de la librería hacia https://api.11111bet.info/v1. Esto permite generar audio de texto a voz de manera sencilla utilizando código estándar sin necesidad de bibliotecas propietarias adicionales.

¿Qué significa tts-1-hd?

Es uno de los dos modelos disponibles en la API. Funciona con el mismo motor que tts-1 y tiene el mismo precio. Ambos modelos tienen el mismo precio por carácter y se seleccionan mediante el campo model en el cuerpo de la solicitud JSON.

¿Cómo obtengo la lista de voces?

Debes realizar una solicitud GET a /v1/voices. Este endpoint devuelve información sobre las voces disponibles, los idiomas soportados, los formatos de audio y los precios. Es la forma oficial de consultar qué opciones de voz y configuración están disponibles para tu integración antes de generar audio.

¿Qué errores devuelve la API?

Si la síntesis falla, la API devuelve un estado de error y la carga se devuelve completamente. Los errores comunes incluyen problemas de autenticación o límites excedidos. No se almacena el audio generado, solo los metadatos de la solicitud para facturación. Revisa el código de estado HTTP para diagnosticar el problema.

¿Puedo especificar el idioma manualmente?

Sí, puedes usar el campo language con un código ISO para forzar un idioma específico. Si no se especifica, el sistema intenta adivinarlo basándose en el script, asumiendo inglés para texto en latín. Es recomendable establecerlo manualmente para textos en latín que no sean inglés para evitar errores.

¿Es necesario usar el SDK oficial?

No, no tenemos un SDK oficial propio. Puedes usar solicitudes HTTP directas o la librería de OpenAI ajustando la URL base. Esto te da flexibilidad para integrar la API en cualquier entorno sin depender de una biblioteca específica, siempre que respetes el formato JSON de la solicitud.

Primera solicitud

curl

curl https://api.11111bet.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.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.11111bet.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.11111bet.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
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

Primeros pasos

Ilustración de onda de sonido para: Primeros pasos

Comienza creando una cuenta en /get-api-key/. Puedes registrarte con Google o con correo y contraseña. Si usas Google, recibirás $0.50 de crédito de prueba válido por 7 días (aproximadamente 50.000 caracteres). Las cuentas por email comienzan sin saldo.

Una vez registrado, la página muestra tu clave API activa y tu saldo actual. Esta clave es tu identificador único para todas las solicitudes. Recuerda que solo puedes tener una clave activa por cuenta; si la renovas, la anterior deja de funcionar inmediatamente.

Obtención de la API Key

Obtención de la API Key

Tu clave API se genera automáticamente al completar el registro. Se muestra en tu panel de control junto con el balance y el uso actual. Copia esta cadena que comienza con 'tts-...' para usarla en tus aplicaciones.

Autenticación Bearer Token

Autenticación Bearer Token

Para autenticar tus solicitudes, incluye la cabecera HTTP: Authorization: Bearer tts-.... Esto permite a la API identificar tu cuenta y deducir el costo de los caracteres procesados. Cada solicitud debe incluir esta cabecera correctamente formateada.

Creación de cuenta

El registro es rápido y no requiere facturación inmediata. Puedes empezar a integrar la API inmediatamente tras la creación. Para recargar saldo, usa USDT (TRC-20) con un mínimo de $5. El saldo no tiene fecha de caducidad.

  • Registro con Google o email
  • Crédito inicial solo con Google
  • Top-ups automáticos por TRC-20

Endpoint principal

Ilustración de onda de sonido para: Endpoint principal

Envía texto y recibe audio con una solicitud POST simple a /v1/audio/speech. Este es el único endpoint necesario para la síntesis.

El sistema procesa las peticiones secuencialmente, lo que puede generar colas bajo carga alta.

POST /v1/audio/speech

El endpoint principal acepta texto y devuelve un archivo de audio binario.

Modelos tts-1 y tts-1-hd

Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio.

Formatos soportados

Puedes solicitar el audio en mp3, wav, opus, flac o pcm. Elige según la compatibilidad de tu reproductor o app de educación lingüística.

  • mp3
  • wav
  • opus
  • flac
  • pcm

Cuerpo de la solicitud

Ilustración de onda de sonido para: Cuerpo de la solicitud

El cuerpo de la solicitud JSON contiene los parámetros esenciales para generar audio. Debes especificar el texto a sintetizar, la voz deseada y la velocidad de reproducción.

Cada campo tiene restricciones claras que debes respetar para evitar errores de validación o cortes en la salida de audio.

Campo input (texto)

El campo input acepta hasta 4096 caracteres por solicitud. Incluye espacios y puntuación en el conteo.

Para textos más largos, divide el contenido en partes de este tamaño y une los archivos de audio resultantes.

  • Límite: 4096 caracteres por petición.

Campo voice (preset)

Selecciona uno de los 8 presets disponibles, como aria o felix. Cada voz tiene un tono distinto, desde narrador claro hasta energético.

  • Opciones: aria, nova, luna, sage, felix, milo, atlas, orion.

Campo speed (0.25–4.0)

Ajusta la velocidad entre 0.25 y 4.0 para adaptar el audio a tu contexto. Valores más altos aceleran la síntesis, útil para lecciones rápidas.

  • Rango: 0.25 a 4.0.

Ejemplo con cURL

Ilustración de onda de sonido para: Ejemplo con cURL

Este ejemplo demuestra una solicitud directa para generar audio MP3 utilizando la herramienta estándar cURL. Es el método más rápido para validar tu integración antes de pasar al código de tu aplicación.

Solo necesitas reemplazar TU_API_KEY con tu credencial real y ajustar el texto de entrada según tu caso de uso en la plataforma de educación lingüística.

Código de ejemplo listo

Copia y ejecuta este comando en tu terminal para recibir un archivo de audio.

```bash curl -X POST "https://api.11111bet.info/v1/audio/speech" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hola, bienvenido a tu lección de idiomas.", "voice": "aria", "response_format": "mp3"}' \ -o audio_generado.mp3 ```

Cabeceras requeridas

La autenticación es crítica. Debes incluir siempre el encabezado Authorization: Bearer TU_API_KEY para que la API reconozca tu cuenta y descuente el saldo correctamente.

El campo Content-Type debe estar configurado como application/json para que el servidor interprete el cuerpo de la solicitud adecuadamente.

Respuesta binaria

Si la solicitud es exitosa, la API devuelve el archivo de audio binario directamente en el cuerpo de la respuesta, sin metadatos JSON adicionales.

Asegúrate de redirigir la salida a un archivo (como audio_generado.mp3 en el ejemplo) para poder reproducirlo o integrarlo en tu aplicación móvil o web inmediatamente.

Uso con SDK de OpenAI

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

La API funciona bajo el mismo esquema de petición que el endpoint de voz de OpenAI, lo que permite reutilizar las bibliotecas oficiales sin adaptar la lógica de negocio. Solo es necesario ajustar la dirección base para dirigir las solicitudes al servicio correcto.

Cambio de base_url

Configura el cliente SDK apuntando a https://api.11111bet.info/v1. Esta dirección reemplaza la URL predeterminada de OpenAI, manteniendo intacta la estructura de los endpoints y los formatos de respuesta.

Configuración del cliente

Inyecta tu clave API (Bearer token) en la cabecera de autorización. El SDK gestionará la serialización JSON y la transmisión de datos binarios de audio sin requerir código adicional de formato.

Compatibilidad de librerías

Utiliza las SDK oficiales de OpenAI para Python o Node.js. Son las librerías recomendadas para interactuar con este endpoint, ya que la API es compatible con el mismo esquema de petición.

Uso con SDK de OpenAI

Gestión de voces

Ilustración de onda de sonido para: Gestión de voces

La gestión de voces se realiza mediante el endpoint GET /v1/voices, que devuelve metadatos detallados sobre cada preset disponible, sus idiomas compatibles y formatos de audio. Este recurso es esencial para construir interfaces de selección intuitivas en tus aplicaciones de aprendizaje de idiomas.

Las voces son presets fijos basados en grabaciones con licencia (LibriTTS-R, CC BY 4.0) y no permiten personalización dinámica. Cada audio generado incluye una marca de agua inaudible que identifica su origen como síntesis.

GET /v1/voices ['Realiza una solicitud GET a /v1/voices para obtener la lista completa de voces disponibles. La respuesta incluye el ID de cada voz, su descripción y los idiomas soportados.', {'h3': 'Listado de 8 presets', 'bullets': ['Aria: Narradora clara y cálida (Femenino)', 'Nova: Voz brillante y enérgica (Femenino)', 'Luna: Suave, ideal para storytelling (Femenino)', 'Sage: Calma e instruccional (Femenino)', 'Felix: Energética, adecuada para promociones (Masculino)', 'Milo: Amigable y conversacional (Masculino)', 'Atlas: Neutral, estilo noticiero (Masculino)', 'Orion: Profunda, ideal para documentales (Masculino)']}, {'h3': 'Idiomas asociados', 'paras': ['Cada voz puede hablar los 23 idiomas soportados. Si no especificas el campo language, el sistema intenta inferirlo; para textos en latín que no sean inglés, es recomendable definirlo explícitamente.']}, 'Modern language learning app interface on a tablet screen showing a voice selection dropdown menu with eight distinct avatar icons and a list of supported languages like Spanish, English, and French in a clean, minimalist design.']

Límites y rendimiento

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

Nuestra API está diseñada para escalar con tu app de aprendizaje de idiomas. Conocer los límites técnicos te ayuda a planificar la generación de audio para lecciones completas sin interrupciones inesperas en la experiencia del usuario.

60 solicitudes por minuto

Cada clave API permite un máximo de 60 solicitudes por minuto. Si tu aplicación genera múltiples ejercicios simultáneamente, es recomendable implementar una lógica de cola interna para distribuir las peticiones y evitar bloqueos temporales.

Límite de 4096 caracteres

Cada petición puede contener hasta 4096 caracteres. Para textos más largos, como una lección de vocabulario extensa, debes dividirlo en fragmentos y unir los archivos de audio resultantes. El espacio y la puntuación cuentan como caracteres.

Colas de procesamiento

Las solicitudes se procesan en orden secuencial. En momentos de alta demanda, una petición puede esperar en cola antes de comenzar. Esto asegura que cada audio se genere con la calidad de voz establecida, aunque la latencia varíe ligeramente.

Errores comunes

Ilustración de onda de sonido para: Errores comunes

En el desarrollo de aplicaciones de aprendizaje de idiomas, los errores de integración suelen ser simples de resolver. Identificar rápidamente el código de estado permite ajustar la lógica de retry o la validación de credenciales sin interrumpir la experiencia del usuario.

Error 401 (clave inválida)

Este error indica que la cabecera Authorization: Bearer tts-... no es válida o ha sido revocada. Si emitiste una nueva clave, la anterior deja de funcionar inmediatamente. Verifica que no haya espacios extra en el token y que la cuenta tenga saldo suficiente.

Error 429 (límite excedido)

Si superas las 60 solicitudes por minuto, recibirás este código. Durante el uso inicial, el límite es de 10 requests/min (antes de la primera recarga). Implementa una lógica de reintento con backoff exponencial para manejar la cola de procesamiento sin saturar la API.

Errores de formato JSON

El endpoint requiere un cuerpo JSON estricto. Asegúrate de que input sea una cadena de texto y que voice coincida con uno de los 8 presets disponibles. Un error de sintaxis JSON devolverá un 400, impidiendo la síntesis hasta corregir la estructura.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Puedes seleccionar el registro adecuado según el tipo de contenido, ya sea un juego de roles o una lectura académica.

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. LibriTTS-R corpus (OpenSLR 141)
  3. W3C WAI: making audio and video accessible
  4. curl documentation
  5. FFmpeg documentation
  6. Tether (USDT)
  7. LibriVox public-domain audiobooks
  8. Python documentation
  9. OpenAI API reference: create speech
  10. openai-node on GitHub
  11. openai-python on GitHub
  12. Creative Commons Attribution 4.0

Más en este sitio