Guía de Implementación para la API de Síntesis de Voz

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

Esta documentación técnica detalla la integración de la API NarraFlow para la síntesis de voz, dirigida específicamente a desarrolladores indie que construyen aplicaciones fintech y sistemas bancarios. Se explica cómo convertir texto plano en archivos de audio mediante una estructura de endpoints simple y predecible, garantizando la compatibilidad con flujos de notificación de clientes sin dependencias complejas.

Se describe el formato de solicitud JSON, la autenticación mediante claves Bearer y el uso de los SDKs oficiales de OpenAI ajustando la base URL. Los ejemplos incluyen comandos cURL listos para producción, manejo de errores comunes como límites de tasa y validación de caracteres, facilitando la implementación rápida en entornos de producción con requisitos estrictos.

Guía de Implementación para la API de Síntesis de Voz

Preguntas frecuentes

¿Cómo se obtiene la clave API inicial?

Regístrese en /get-api-key/ con Google o correo electrónico. Google otorga una prueba de $0.50; las cuentas con correo electrónico y contraseña comienzan sin crédito de prueba. La clave se emite al instante y se usa en el encabezado Authorization: Bearer tts-...

¿Qué formato de respuesta devuelve la API?

La API devuelve el archivo de audio binario directamente en el cuerpo de la respuesta HTTP. El formato depende del campo response_format especificado (mp3, wav, opus, flac, pcm). No se devuelve JSON con el audio codificado, sino el flujo de audio crudo.

¿Se puede usar la API desde un navegador?

Sí, mediante una solicitud POST a https://api.canadiandollarbingo.info/v1/audio/speech. Debe incluir el encabezado Authorization con su clave Bearer. Tenga en cuenta que la clave será visible en el código del cliente si se usa directamente desde el navegador.

¿Qué sucede si se excede el límite de velocidad?

El límite es de 60 solicitudes por minuto por clave (10 antes del primer recargo). Si excede el límite, las solicitudes adicionales recibirán un error. Las solicitudes fallidas son gratuitas y el cargo se devuelve en su totalidad.

¿Es compatible la API con Python?

Sí, es compatible con el SDK oficial de OpenAI para Python. Solo debe cambiar el base_url a https://api.canadiandollarbingo.info/v1 y usar su clave de NarraFlow. También funciona con cualquier cliente HTTP estándar como requests o urllib.

¿Se puede especificar el idioma en la solicitud?

Sí, mediante el campo language con un código ISO. Si no se especifica, se deduce del script (latín por defecto inglés). Para textos en latín no ingleses, especifique el idioma explícitamente para evitar errores de síntesis automática.

¿Cuál es la diferencia entre tts-1 y tts-1-hd?

Ambos modelos usan el mismo motor de síntesis y tienen el mismo precio: $0.01 por 1000 caracteres. La única diferencia es la calidad de audio percibida, pero funcionalmente y económicamente son idénticos para la integración de la API.

¿Cómo se manejan los caracteres especiales?

Los caracteres especiales cuentan como caracteres para el límite de 4096 caracteres por solicitud y para la facturación. La API procesa el texto plano directamente sin necesidad de codificación especial, siempre que la codificación de la solicitud sea UTF-8.

¿La API devuelve el audio en base64?

No. La API devuelve el archivo de audio binario directamente en el cuerpo de la respuesta HTTP. No utiliza codificación base64. Debe manejar la respuesta como un flujo de bytes para guardar el archivo en el formato solicitado.

¿Se puede usar la API con Node.js?

Sí, mediante el SDK de OpenAI para Node.js. Configure base_url a https://api.canadiandollarbingo.info/v1 y use su clave NarraFlow. También es compatible con fetch o axios para realizar solicitudes HTTP POST estándar al endpoint de speech.

¿Qué hace el campo response_format?

Define el formato del archivo de audio generado. Las opciones disponibles son mp3, wav, opus, flac y pcm. El formato elegido determina el contenido del cuerpo de la respuesta HTTP y el tipo de archivo que recibirá.

¿Se puede cancelar una solicitud en curso?

No hay un mecanismo de cancelación explícito en la API. Las solicitudes se procesan en cola y una vez iniciadas, se completan. Si falla la síntesis, el cargo se devuelve en su totalidad.

¿Hay un límite de tiempo para la respuesta?

La generación es aproximadamente en tiempo real (25 caracteres por segundo). Las solicitudes pueden esperar en cola bajo carga. Para textos largos, la respuesta tardará varios segundos o minutos.

¿Se requiere una versión específica del SDK?

No se requiere una versión específica. Cualquier versión del SDK de OpenAI que soporte el endpoint de speech funciona, siempre que se ajuste el base_url. La compatibilidad depende de la estructura del cuerpo JSON, que sigue el estándar de OpenAI.

Primera solicitud

curl

curl https://api.canadiandollarbingo.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.canadiandollarbingo.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.canadiandollarbingo.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

Autenticación y Claves

Ilustración de onda de sonido para: Autenticación y Claves

La API requiere autenticación mediante un token Bearer en el encabezado de cada solicitud. Utilice su clave API única obtenida en /get-api-key/ para autorizar las peticiones de síntesis.

Formato de la clave Bearer

Formato de la clave Bearer

Incluya el encabezado Authorization: Bearer tts-... en cada llamada HTTP. Esta clave es el único mecanismo de acceso para su cuenta en este sitio.

Emisión de nueva clave

Emisión de nueva clave

Puede generar una nueva clave API en cualquier momento desde su panel de cuenta. Esto es útil para rotar credenciales o revocar acceso a entornos específicos.

Invalidez inmediata de clave antigua

Al emitir una nueva clave, la anterior deja de ser válida de forma instantánea. Asegúrese de actualizar las configuraciones en sus servicios fintech para evitar errores 401.

Endpoint principal de síntesis

Ilustración de onda de sonido para: Endpoint principal de síntesis

El endpoint principal para la generación de audio es POST https://api.canadiandollarbingo.info/v1/audio/speech. Este punto final recibe texto plano y devuelve el archivo de audio sintetizado, actuando como el núcleo de la integración para notificaciones fintech.

La solicitud requiere un cuerpo JSON con los parámetros de síntesis. La respuesta contiene el audio binario directamente en el stream de salida, listo para ser reproducido o almacenado por la aplicación cliente.

Método POST y URL

Utilice el método HTTP POST dirigido a la ruta /v1/audio/speech dentro de la base https://api.canadiandollarbingo.info/v1. Este es el único punto de entrada necesario para la generación de audio.

La URL debe ser accesible desde su entorno de desarrollo o producción sin necesidad de puertos personalizados. Todas las solicitudes pasan por este único endpoint para garantizar la consistencia en el procesamiento.

Cuerpo de la solicitud JSON

El cuerpo de la solicitud debe ser un objeto JSON que contenga los campos model, input, voice y response_format. El campo input acepta hasta 4096 caracteres de texto plano.

Se pueden incluir opcionalmente speed (entre 0.25 y 4.0) y language (código ISO). El modelo tts-1 o tts-1-hd determina la calidad del motor de síntesis utilizado.

La estructura es idéntica a la de la API de OpenAI, facilitando la migración o integración inmediata si ya utiliza sus librerías estándar.

  • model: "tts-1" o "tts-1-hd"
  • input: texto plano (máx. 4096 caracteres)
  • voice: uno de los 8 presets disponibles
  • response_format: mp3, wav, opus, flac o pcm

Códigos de estado HTTP

Un estado 200 OK indica que la síntesis se completó exitosamente y la respuesta contiene el archivo de audio binario correspondiente al formato solicitado.

Los errores como 400 Bad Request indican parámetros faltantes o inválidos en el JSON. El sistema no almacena el audio generado, por lo que debe ser procesado inmediatamente por el cliente.

Si la síntesis falla durante el procesamiento, la solicitud se marca como fallida y no se realiza ningún cargo a su saldo.

Parámetros de la solicitud

Ilustración de onda de sonido para: Parámetros de la solicitud

La API requiere parámetros específicos para generar audio preciso. El campo input acepta texto plano con un límite estricto de 4096 caracteres, que incluyen espacios y puntuación. Para textos más largos, es necesario dividir la entrada y unir los archivos resultantes.

La selección del modelo y la voz define la salida final. El modelo tts-1 o tts-1-hd utiliza el mismo motor y precio. Las ocho voces disponibles están optimizadas para diferentes contextos de comunicación financiera y notificaciones.

Campo input con texto plano

El parámetro input recibe la cadena de texto a sintetizar. El límite es de 4096 caracteres por solicitud, contando espacios y puntuación. Si el texto excede este valor, debe segmentarse manualmente para evitar errores.

Modelo tts-1 o tts-1-hd

Ambos modelos utilizan el mismo motor de síntesis y tienen idéntico costo. La elección no afecta el precio, solo la configuración interna del procesamiento.

Voz y formato de respuesta

Seleccione una de las ocho voces predefinidas (ej. aria, nova, atlas). El formato de salida puede ser mp3, wav, opus, flac o pcm. La velocidad ajustable oscila entre 0.25 y 4.0.

  • Voces: aria, nova, luna, sage, felix, milo, atlas, orion
  • Formatos: mp3, wav, opus, flac, pcm
  • Velocidad: 0.25 a 4.0

Ejemplo de solicitud Curl

Ilustración de onda de sonido para: Ejemplo de solicitud Curl

Copia y ejecuta este comando para generar audio. Reemplaza TUS_CLAVE_AQUI con tu clave Bearer y ajusta el texto de entrada.

La API devuelve el archivo de audio directamente en el cuerpo de la respuesta HTTP, listo para su procesamiento inmediato.

Comando completo listo para copiar

Este comando envía una solicitud POST a la API de NarraFlow.

El modelo tts-1 o tts-1-hd utiliza el mismo motor y precio.

  • Reemplaza TU_API_KEY con tu clave real.
  • Ajusta el texto en el campo input según tu necesidad.

Manejo de la respuesta binaria

La respuesta contiene datos binarios puros. Guarda el resultado en un archivo con la extensión adecuada.

No se incluye metadatos JSON en el cuerpo cuando la solicitud es exitosa.

Verificación de estado 200 OK

Un código 200 indica que el audio se generó correctamente. Verifica que el archivo tenga el tamaño esperado.

Si recibes 401, 429 o 413, revisa la sección de errores.

Uso con SDK de OpenAI

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

El SDK oficial de OpenAI funciona directamente con NarraFlow si se ajusta la URL base. Esto permite reutilizar el código de integración existente sin importar la librería cliente nativa.

Cambio de base_url

Configura la variable de entorno o el parámetro de inicialización base_url con el valor https://api.canadiandollarbingo.info/v1. Esta modificación redirige las llamadas al endpoint de síntesis de voz de NarraFlow.

Uso de la misma clave API

La autenticación utiliza exactamente el mismo formato Bearer y la clave tts-... generada en tu panel. No es necesario cambiar el encabezado de autorización ni registrar una credencial separada.

Compatibilidad de librerías

Cualquier librería cliente de OpenAI compatible con el endpoint /v1/audio/speech es funcional. Esto incluye las versiones recientes de Python, Node.js y otros idiomas soportados por el SDK oficial.

Uso con SDK de OpenAI

Manejo de errores comunes

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

La API devuelve códigos HTTP estándar para indicar el estado de cada solicitud. Un error 401 indica que la clave Bearer es inválida o ha sido revocada tras la emisión de una nueva. Un error 429 señala que se ha excedido el límite de 60 solicitudes por minuto. Un error 413 ocurre cuando el texto excede los 4096 caracteres permitidos por llamada.

Error 401 por clave inválida

Este error indica que la cabecera Authorization no contiene una clave activa válida. Al emitir una nueva clave, la anterior deja de funcionar de forma inmediata. Verifique que la clave comienza con tts- y que no haya caracteres extra.

Error 429 por límites de tasa

Se devuelve al superar los 60 solicitudes por minuto por clave. Los nuevos usuarios tienen un límite de 10 solicitudes por minuto hasta la primera recarga. Implemente una lógica de reintentos con backoff exponencial para manejar la cola de procesamiento.

  • Límite base: 10 req/min antes del primer pago.
  • Límite estándar: 60 req/min por clave activa.
  • Verifique la cabecera Retry-After si está presente.

Error 413 por texto demasiado largo

Ocurre si el campo input supera los 4096 caracteres. Para textos largos, divida la entrada en fragmentos manejables y unae los archivos de audio resultantes manualmente en su aplicación fintech.

Límites de la API

Ilustración de onda de sonido para: Límites de la API

La API aplica un límite de 60 solicitudes por minuto por clave. Antes de la primera recarga, este límite se reduce a 10 solicitudes por minuto. Los límites se aplican por clave.

60 solicitudes por minuto

Cada clave activa tiene un límite de 60 solicitudes por minuto. Antes de la primera recarga de saldo, el límite es de 10 solicitudes por minuto. Se recomienda usar un único cliente o implementar backoff exponencial para evitar errores 429.

4096 caracteres por solicitud

Cada solicitud puede contener hasta 4096 caracteres de texto plano. Para textos más largos, es necesario dividir el texto en partes y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres.

Velocidad de generación real

La generación es aproximadamente en tiempo real, con una tasa de 25 caracteres por segundo de audio generado. Las frases cortas pueden tardar unos segundos adicionales debido a la inicialización. Las solicitudes se procesan en cola bajo carga.

Formatos de audio soportados

Ilustración de onda de sonido para: Formatos de audio soportados

La API permite seleccionar el formato de audio en la respuesta mediante el campo response_format. Este parámetro determina la codificación del archivo de audio devuelto, adaptándose a las necesidades de almacenamiento y reproducción de cada integración fintech.

Los formatos disponibles son mp3, wav, opus, flac y pcm. La elección depende del balance entre calidad, tamaño de archivo y compatibilidad del cliente final con la notificación de voz.

MP3 para compresión web

El formato MP3 ofrece una compresión con pérdida eficiente, reduciendo significativamente el tamaño de los archivos de audio. Es ideal para aplicaciones móviles o web donde el ancho de banda y el almacenamiento son limitados, manteniendo una calidad de escucha aceptable para notificaciones rápidas.

WAV para calidad sin pérdida

WAV proporciona audio sin pérdida de calidad, preservando todos los detalles del habla sintetizada. Este formato es adecuado para sistemas de backend que requieren máxima fidelidad o para archivado de notificaciones críticas donde la integridad del audio es prioritaria sobre el tamaño del archivo.

OPUS y FLAC para eficiencia

OPUS y FLAC son formatos de compresión eficientes. Ambos formatos son útiles para optimizar el almacenamiento a largo plazo o para entornos que requieren alta eficiencia sin sacrificar la claridad del mensaje.

  • MP3: Ideal para ancho de banda limitado.
  • WAV: Máxima fidelidad sin compresión.
  • OPUS: Eficiente para transmisión.
  • FLAC: Compresión sin pérdida.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Verifique el saldo y el consumo en la página de su cuenta para evitar sorpresas.

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. MDN: Web Speech API
  3. LibriTTS-R corpus (OpenSLR 141)
  4. Node.js documentation
  5. Creative Commons Attribution 4.0
  6. W3C WAI: making audio and video accessible
  7. Python documentation
  8. OpenAI API reference: create speech
  9. Tether (USDT)
  10. TRON developer hub: TRC-20
  11. openai-python on GitHub
  12. FFmpeg documentation

Más en este sitio