Preguntas frecuentes
¿Qué formato de audio se recomienda para apps móviles?
El formato MP3 es una opción común para aplicaciones móviles debido a su amplio soporte y tamaño de archivo reducido. También puedes elegir WAV para calidad sin pérdida, u OPUS y FLAC si necesitas compresión avanzada. El formato PCM está disponible para procesamiento sin compresión. La elección depende de tus requisitos de almacenamiento y latencia, pero MP3 suele ser el estándar para la distribución de audio en entornos móviles.
¿Cómo se cambia la base_url en el SDK?
Para utilizar este servicio con los SDKs oficiales, debes modificar la variable base_url para que apunte a https://api.getx33.com/v1. Esto permite que las solicitudes se dirijan correctamente a nuestra infraestructura. Asegúrate de actualizar también la clave de autorización con tu token único. Esta configuración es idéntica a la de otros servicios compatibles, facilitando la integración sin necesidad de aprender una nueva estructura de endpoints.
¿Se pueden usar los SDKs oficiales de OpenAI?
Sí, la API es compatible con los SDKs oficiales de OpenAI. Solo necesitas ajustar la base_url a https://api.getx33.com/v1 y usar tu propia clave de API. La estructura del cuerpo de la solicitud es la misma, lo que permite una integración rápida sin cambios mayores en tu código. Esto facilita la migración o el uso de herramientas existentes que ya dependen de estas bibliotecas estándar.
¿Qué hace el parámetro language?
El parámetro language permite especificar el código ISO del idioma para la síntesis. Si no se establece, el sistema intenta adivinar el idioma basado en el script del texto, asumiendo inglés para texto en latín. Para textos en otros idiomas con caracteres latinos, es recomendable definir este campo explícitamente para garantizar una pronunciación correcta y evitar errores de interpretación automática del idioma.
¿Cuál es la diferencia entre tts-1 y tts-1-hd?
Ambos modelos, tts-1 y tts-1-hd, utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio. Para la mayoría de las notificaciones de banca y fintech, la diferencia es mínima, pero puedes elegir la versión estándar para optimizar costos sin sacrificar la claridad.
¿Cómo se manejan los textos largos?
Cada solicitud tiene un límite de 4096 caracteres. Para textos más largos, debes dividirlos en partes dentro de este límite y generar cada segmento por separado. Luego, puedes unir los archivos de audio resultantes en tu aplicación. Esta estrategia asegura que cada solicitud se procese correctamente y evita errores de límite. El tiempo de generación es aproximadamente en tiempo real para textos extensos.
¿Qué sucede si se excede el límite de velocidad?
El límite es de 60 solicitudes por minuto por clave de API. Si excedes este umbral, las solicitudes adicionales pueden tardar más en procesarse debido a la cola de espera. Las solicitudes fallidas no se cobran. Para la mayoría de las integraciones de notificaciones, este límite es suficiente. Si necesitas mayor throughput, considera distribuir las solicitudes entre múltiples claves o ajustar la frecuencia de generación.
¿Se puede pasar una lista de voces?
No, la API acepta una única voz por solicitud en el campo voice. Puedes elegir entre ocho presets disponibles, como Aria, Nova o Felix. Si necesitas diferentes voces en una misma respuesta, debes realizar múltiples solicitudes y unir los archivos de audio resultantes. No hay un parámetro para generar varias voces simultáneamente en un solo archivo de audio generado por la API.
Primera solicitud
curl
curl https://api.getx33.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.getx33.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.getx33.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 | |
|---|---|
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 |
Obtención de clave API
Accede a /get-api-key/ para obtener tu clave. El registro con Google otorga $0.50 de crédito de prueba válido por 7 días. Con email y contraseña, comienzas sin crédito inicial.
Registro con Google
Inicia sesión con tu cuenta de Google en /get-api-key/. El sistema genera automáticamente una clave API y acredita $0.50 (aproximadamente 50.000 caracteres) para probar la integración.
- Crédito de prueba: $0.50 válido por 7 días.
- Generación instantánea de clave API.
- Sin necesidad de tarjeta de crédito.
Registro con email
Crea una cuenta con correo y contraseña. A diferencia del registro con Google, este método no incluye crédito de prueba inicial. Deberás realizar un depósito en USDT (TRC-20) para comenzar a generar audio.
- Autenticación estándar con email/contraseña.
- Sin crédito de prueba automático.
- Ideal para cuentas corporativas o de producción.
Gestión de claves
La página de tu cuenta muestra tu clave activa, saldo y uso. Puedes emitir una nueva clave en cualquier momento; la anterior deja de funcionar inmediatamente. Mantén una sola clave activa por seguridad.
- Una clave activa por cuenta.
- Revocación instantánea al emitir una nueva.
- Visualización de saldo y caracteres restantes.
Primera solicitud con cURL
Para generar audio, envía un POST a https://api.getx33.com/v1/audio/speech. El cuerpo JSON requiere el texto a convertir y la voz deseada. La API responde con el archivo de audio generado o un error si la síntesis falla.
Estructura JSON
La solicitud debe incluir el campo input con el texto (máx. 4096 caracteres) y voice con uno de los 8 preset disponibles. El modelo tts-1 o tts-1-hd determina la calidad base.
Parámetros requeridos
Además de input y voice, debes especificar response_format (mp3, wav, opus, flac, pcm). El campo language es opcional; si no se define, el sistema detecta el idioma por el script, asumiendo inglés para texto latino.
- Modelo: tts-1 o tts-1-hd
- Input: texto hasta 4096 caracteres
- Voice: nombre del preset (ej. 'nova')
- Response_format: mp3, wav, opus, flac, pcm
Respuesta de audio
La API devuelve el archivo de audio directamente en la respuesta. Si la síntesis falla, no se cobra y se devuelve un código de error. Para textos largos, se recomienda dividir en partes y unir los archivos resultantes.
Integración con SDK OpenAI
La API de VozBanco mantiene la misma estructura de solicitud que el endpoint de OpenAI, lo que permite reutilizar clientes oficiales sin reescribir la lógica de llamada. Solo necesitas ajustar la URL base para apuntar a nuestra infraestructura.
Cambio de base_url
Configura el cliente para que apunte a https://api.getx33.com/v1. Esto asegura que las solicitudes se enruten correctamente hacia el servicio de síntesis de voz de VozBanco.
Uso del cliente Python
Instala la librería oficial de OpenAI. Inicializa la clase OpenAI pasando tu clave API y la nueva base_url. Luego, invoca el método audio.speech con los parámetros estándar.
- Requiere la librería
openai. - Define
base_urlen la configuración inicial.
Uso del cliente Node.js
Npm instala el paquete openai. Crea una instancia del cliente con la clave y la URL base modificada. Ejecuta audio.speech para generar el audio.
- Usa
npm install openai. - Ajusta
apiKeyybaseURL.
Formatos de audio
La API de VozBanco ofrece múltiples formatos de audio para adaptarse a las necesidades técnicas de tu aplicación fintech. Puedes elegir entre formatos con compresión para optimizar el ancho de banda o formatos sin pérdida para máxima fidelidad, todos generados mediante la misma API REST.
El formato seleccionado se especifica en el campo response_format de la solicitud JSON. La elección afecta el tamaño del archivo resultante, pero no la calidad de la voz ni el procesamiento, que permanece idéntico independientemente del contenedor elegido.
MP3 para web
Es el formato más utilizado para la reproducción en aplicaciones web y móviles modernas. Ofrece una buena relación entre calidad y tamaño de archivo, lo que reduce el consumo de datos para los usuarios finales al descargar las notificaciones de pagos o alertas.
El MP3 es ampliamente compatible con todos los navegadores y reproductores nativos de iOS y Android, facilitando la implementación rápida en la interfaz de usuario de tu plataforma financiera.
- Tamaño de archivo optimizado para carga rápida.
- Amplia compatibilidad con navegadores y dispositivos móviles.
- Ideal para notificaciones push y reproductores integrados en la app.
WAV para alta calidad
Proporciona audio sin pérdida de calidad, manteniendo el formato de datos de audio original. Es el formato recomendado cuando necesitas la máxima fidelidad para validaciones auditivas o análisis de calidad de voz.
Aunque los archivos WAV son significativamente más grandes que los MP3, garantizan que cada matiz de la voz natural se reproduzca con precisión, ideal para sistemas de auditoría interna o calidad de servicio.
- Audio sin pérdida de datos.
- Mayor tamaño de archivo y ancho de banda.
- Ideal para archivado y análisis de alta fidelidad.
OPUS, FLAC, PCM
OPUS ofrece una compresión eficiente, ideal para entornos con ancho de banda limitado. FLAC es una compresión sin pérdida, manteniendo la calidad original con un tamaño menor que WAV.
PCM es audio sin comprimir en bruto, útil para procesamiento posterior o integración con sistemas legacy que requieren datos de audio sin codificar. Cada formato se selecciona según los requisitos específicos de infraestructura de tu equipo de producto.
- OPUS: compresión eficiente para baja latencia.
- FLAC: compresión sin pérdida, menor que WAV.
- PCM: audio crudo sin codificar para procesamiento interno.
Manejo de errores
La API devuelve códigos HTTP estándar para indicar el estado de cada solicitud. Un código 200 confirma que el audio se generó correctamente. Los códigos 4xx indican problemas con la solicitud, mientras que los 5xx señalan fallos internos del servicio.
Códigos de estado HTTP
El código 200 OK devuelve el archivo de audio binario. El 400 Bad Request indica que el JSON enviado es inválido. El 401 Unauthorized significa que la clave API es incorrecta. El 429 Too Many Requests aparece al superar los 60 solicitudes por minuto.
Los errores 500 o 503 son temporales y suelen resolverse reintentando la solicitud tras unos segundos.
- 200: Éxito, audio disponible en la respuesta
- 400: Formato JSON inválido o campos faltantes
- 401: Clave API incorrecta o inválida
- 429: Límite de velocidad excedido (60 req/min)
Errores de entrada
Los errores de entrada ocurren cuando los parámetros no cumplen los requisitos. Por ejemplo, si el texto excede los 4096 caracteres o si la voz especificada no existe en la lista de 8 disponibles.
También se devuelve un error si el formato de audio solicitado no es válido (mp3, wav, opus, flac, pcm) o si la velocidad está fuera del rango 0.25–4.0.
- Texto mayor a 4096 caracteres
- Voz no existente en el catálogo
- Formato de audio no soportado
- Velocidad fuera del rango 0.25–4.0
Errores de servidor
Los errores del servidor son raros pero pueden ocurrir durante picos de demanda. Si la síntesis falla, el cargo se devuelve íntegramente.
Se recomienda implementar una lógica de reintento con retroceso exponencial para manejar fallos temporales 500 o 503 sin afectar la experiencia del usuario final.
- 500: Error interno del servidor
- 503: Servicio no disponible temporalmente
- Reintento recomendado con backoff exponencial

Límites de velocidad
La API permite un máximo de 60 solicitudes por minuto por clave, un límite suficiente para la mayoría de los flujos de notificaciones en tiempo real. Este umbral asegura una distribución equilibrada de recursos sin afectar la latencia de las alertas críticas.
60 solicitudes por minuto
Cada clave de API tiene un límite de 60 solicitudes por minuto. Esto permite generar audio para múltiples usuarios simultáneamente, siempre que se respete el límite de caracteres por solicitud (4096).
- Límite estándar por clave activa
- Adecuado para picos de notificaciones
Límite inicial
Al crear una cuenta nueva, el límite es de 10 solicitudes por minuto. Este valor aumenta automáticamente a 60 después de la primera recarga de saldo. Es importante verificar este límite antes de lanzar campañas masivas.
- 10 req/min sin recarga
- 60 req/min con saldo
Cola de procesamiento
Las solicitudes se procesan en orden secuencial. Si se excede la capacidad inmediata, las peticiones adicionales se colocan en una cola. El tiempo de espera varía según la carga del servidor, pero la integridad del audio se garantiza.
- Procesamiento secuencial
- Cola automática bajo carga
Campos de solicitud
Para generar audio mediante la API de VozBanco, debes estructurar el cuerpo de tu solicitud JSON con los campos específicos que definen cómo se sintetizará el texto. Estos parámetros son fundamentales para garantizar que las notificaciones de pagos o alertas de seguridad suenen naturales y se integren correctamente en tu aplicación fintech.
Modelo tts-1 o tts-1-hd
Selecciona "tts-1" o "tts-1-hd" según tu necesidad de calidad. Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio, por lo que la elección depende exclusivamente de si prefieres el formato de audio estándar o la versión de alta definición sin costo adicional.
Voz específica
El campo voice debe contener uno de los ocho presets disponibles. Cada voz tiene un tono distinto, desde la narradora clara de Aria hasta la voz profunda de Orion, permitiendo elegir el estilo más adecuado para el tipo de notificación que estás enviando.
- aria: cálida, narradora clara
- nova: brillante, enérgica
- luna: suave, storytelling
- sage: calmada, instruccional
- felix: enérgica, promo
- milo: amigable, conversacional
- atlas: neutral, news
- orion: profunda, documentary
Idioma opcional
Puedes especificar el código ISO del idioma en el campo language. Si no lo estableces, el sistema detectará el idioma basándose en la escritura; el texto en latín por defecto se asume como inglés. Para textos en latín que no sean inglés, es obligatorio configurar este campo para evitar errores de síntesis.
Autenticación
La autenticación se gestiona mediante un token único asociado a tu cuenta. Para validar cada solicitud, debes incluir el encabezado de autorización en la cabecera HTTP, asegurando que el sistema reconozca tu identidad y descargue el saldo correspondiente.
Encabezado Authorization
Incluye el encabezado Authorization: Bearer <tu-clave> en cada petición POST. Este token actúa como tu credencial única para acceder a los endpoints de síntesis.
Formato Bearer
El formato debe ser estrictamente Bearer seguido del valor de tu clave API. No añades prefijos adicionales ni comillas extra alrededor del token en la cabecera HTTP.
Una clave activa
Cada cuenta mantiene una sola clave activa. Si emites una nueva, la anterior deja de funcionar inmediatamente. Esto simplifica la gestión de seguridad en tus entornos de producción.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Si el texto de la alerta no varía, guarda el archivo de audio generado y reutilízalo.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
