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.mp3Python (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 | |
|---|---|
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 |
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
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
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
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
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
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_KEYcon tu clave real. - Ajusta el texto en el campo
inputsegú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
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.

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
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
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.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
