Preguntas frecuentes
¿Qué formato de respuesta devuelve la API?
La API devuelve el archivo de audio directamente en el cuerpo de la respuesta. Puedes elegir entre los formatos mp3, wav, opus, flac o pcm especificando el campo response_format en tu solicitud JSON. No se devuelve metadatos adicionales junto al audio, solo el binario del archivo generado listo para su reproducción o descarga inmediata.
¿Puedo usar la librería de Python de OpenAI?
Sí, la forma de solicitud es idéntica a la de OpenAI. Solo necesitas cambiar la base_url a https://api.winslots777.info/v1 y utilizar tu clave de API en su lugar. Esto permite usar las librerías de OpenAI ajustando la URL base.
¿Cuál es el límite de caracteres por petición?
Cada solicitud individual acepta un máximo de 4096 caracteres en el campo input. Si tu texto supera este límite, debes dividirlo en partes más pequeñas y enviar múltiples solicitudes. Cada parte generará un archivo de audio independiente que luego deberás unir para obtener la narración completa.
¿Cómo manejo textos largos en la API?
Debes dividir tu texto en fragmentos de hasta 4096 caracteres y enviar una solicitud POST por cada fragmento. Luego, une los archivos de audio resultantes en el orden correcto. Las solicitudes se procesan secuencialmente, por lo que textos muy largos pueden tardar más debido a la cola de procesamiento.
¿Qué hace el modelo tts-1-hd?
El modelo tts-1-hd utiliza el mismo motor de síntesis y tiene el mismo precio que tts-1. La única diferencia es la etiqueta de calidad del modelo seleccionado en la solicitud. Ambos modelos generan audio con la misma velocidad y características técnicas, ofreciendo la misma experiencia de narración.
¿La API soporta streaming?
No, la API no ofrece streaming ni WebSockets para audio parcial. Devuelve el archivo completo una vez finalizada la síntesis. Las solicitudes se procesan una tras otra, por lo que bajo carga una petición puede esperar en cola antes de generar y devolver el audio completo.
¿Puedo cambiar la velocidad en tiempo real?
La velocidad se define en cada solicitud mediante el parámetro speed, con un rango de 0.25 a 4.0. No es posible ajustar la velocidad dinámicamente mientras se reproduce el audio. Debes especificar la velocidad deseada en cada llamada a la API antes de que se genere el archivo.
¿Cómo se mide el uso de caracteres?
Se facturan 10 dólares por cada millón de caracteres, donde los espacios y la puntuación cuentan como caracteres. El límite es de 4096 caracteres por petición. Los caracteres se cuentan en el campo input de tu solicitud JSON antes de enviarla a la API para la síntesis.
Primera solicitud
curl
curl https://api.winslots777.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.winslots777.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.winslots777.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
La autenticación se realiza mediante una clave API enviada en el encabezado Authorization como token Bearer. Cada cuenta mantiene una sola clave activa válida para todas las peticiones.
Esta clave debe obtenerse desde la página /get-api-key/ y se utiliza en cada llamada a la API para identificar tu cuenta y facturar los caracteres generados.
Uso de clave Bearer
Incluye el encabezado Authorization: Bearer tts-tu-clave-aqui en cada solicitud HTTP. La API verifica la validez de la clave antes de procesar el texto o asignar costo.
Obtención desde /get-api-key/
Navega a la ruta /get-api-key/ tras registrarte con Google o correo electrónico. Allí verás tu clave activa, el saldo disponible y el historial de uso.
Invalidación inmediata al cambiar clave
Al generar una nueva clave desde tu panel, la anterior deja de funcionar instantáneamente. Asegúrate de actualizar la variable de entorno en tus scripts para evitar errores 401.
Endpoint principal
El endpoint principal de la API es POST https://api.winslots777.info/v1/audio/speech. Este punto de entrada procesa la solicitud de síntesis y devuelve el archivo de audio generado directamente en la respuesta.
Es el único punto necesario para convertir texto en audio. Solo requiere enviar el cuerpo JSON con el texto y la voz deseada, sin necesidad de gestión de sesiones o estados previos.
Método POST /v1/audio/speech
Envía una petición POST a la ruta /v1/audio/speech de la API base. La solicitud debe incluir la cabecera Authorization con la clave Bearer y el cuerpo JSON con los parámetros de generación.
- Método: POST
- Ruta: /v1/audio/speech
- Formato: application/json
Cuerpo JSON con input y voice
El cuerpo de la petición debe contener el campo input con el texto a narrar (máximo 4096 caracteres) y voice con uno de los 8 presets disponibles (ej. aria, nova, felix). También puedes incluir model, response_format y speed.
Si omites language, el sistema intenta adivinarlo por el script, pero para textos en latín distintos al inglés es recomendable especificarlo explícitamente para asegurar la pronunciación correcta.
input: Texto (≤4096 caracteres)voice: ID de voz (ej. 'nova')model: 'tts-1' o 'tts-1-hd'speed: 0.25 a 4.0
Retorno de archivo de audio
La respuesta contiene el archivo de audio en el formato solicitado (response_format: mp3, wav, opus, flac, pcm). Si la síntesis falla, se devuelve un error JSON sin cargo. En caso de éxito, recibe el binario directamente.
Ejemplo de integración
Puedes usar el SDK oficial de OpenAI cambiando base_url a https://api.winslots777.info/v1. Esto permite usar client.audio.speech() ajustando la URL base, aprovechando la compatibilidad con el esquema de solicitud de OpenAI.
Comando cURL de ejemplo
La forma más directa de validar la integración es mediante una solicitud HTTP básica. Este enfoque permite generar audio sin depender de librerías externas ni configurar entornos complejos, ideal para pruebas rápidas en terminales o scripts simples.
El comando utiliza el método POST sobre el endpoint principal, enviando los parámetros esenciales en formato JSON. La respuesta devuelve el archivo de audio generado directamente, listo para ser guardado o reproducido en tu flujo de trabajo.
Código de petición básico
Envía una petición POST al endpoint /v1/audio/speech. El cuerpo debe contener el model (tts-1 o tts-1-hd), el input con el texto a narrar y el voice deseado.
- Método: POST
- Endpoint: https://api.winslots777.info/v1/audio/speech
- Content-Type: application/json
Inclusión de clave API
La autenticación se realiza mediante un encabezado Bearer. Usa la clave generada en /get-api-key/ para autorizar la solicitud y evitar errores 401.
Recepción de respuesta binaria
La respuesta contiene el archivo de audio binario en el formato solicitado. Guarda la salida estándar directamente en un archivo local para su uso posterior.
Integración con SDK OpenAI
La API de Narras mantiene la misma estructura de peticiones que el endpoint de OpenAI, lo que permite reutilizar librerías oficiales sin reescribir la lógica de conexión. Solo es necesario ajustar la URL base para dirigir las llamadas a nuestro servicio.
Cambio de base_url
Configura la URL base de tu cliente SDK a https://api.winslots777.info/v1. Esto redirige todas las peticiones hacia nuestra infraestructura manteniendo la compatibilidad con las claves de API existentes.
Compatibilidad con librerías oficiales
Las librerías de OpenAI funcionan correctamente al modificar este parámetro. No se requiere un SDK propietario ni adaptadores adicionales, lo que simplifica la integración en proyectos Python o Node.js.
Uso de client.audio.speech
Invoca el método client.audio.speech enviando el texto y la voz deseada. El SDK gestionará la serialización JSON y la recepción del archivo de audio generado.
Parámetros de la petición
La configuración de la síntesis se controla mediante tres campos clave en el cuerpo JSON. El modelo determina la calidad base, mientras que la voz asigna el timbre vocal y la velocidad ajusta la duración del audio generado.
Estos parámetros permiten adaptar rápidamente la salida a diferentes estilos de narración, desde locuciones rápidas para videos dinámicos hasta lecturas pausadas para contenido educativo, sin necesidad de post-procesamiento complejo.
Modelo tts-1 o tts-1-hd
El campo model acepta dos valores: tts-1 o tts-1-hd. Ambos utilizan exactamente el mismo motor de síntesis y tienen el mismo precio por carácter, por lo que la selección depende exclusivamente de la preferencia de calidad de audio percibida, no de un diferencial de costo o capacidad técnica entre ellos.
Voz seleccionada entre 8 presets
Debes especificar una de las ocho voces predefinidas mediante el campo voice. Cada voz tiene un perfil distinto: desde aria (narradora clara) hasta atlas (neutral, ideal para noticias) o orion (profundo, para documentales). La voz elegida determina el timbre, pero puede hablar en cualquiera de los 23 idiomas soportados.
- aria: narradora cálida y clara
- nova: brillante y enérgica
- luna: suave, para historias
- sage: calmada e instructiva
- felix: dinámica, para promos
- milo: amigable y conversacional
- atlas: neutral, estilo noticioso
- orion: profunda, estilo documental
Velocidad de 0.25 a 4.0
El parámetro speed permite ajustar la velocidad de habla entre 0.25 (muy lento) y 4.0 (muy rápido). El valor predeterminado es 1.0. Ajustar esta velocidad es útil para sincronizar la narración con el ritmo visual del video o para hacer que textos largos suenen más concisos.

Formatos de salida
La API permite generar audio en cinco formatos diferentes: mp3, wav, opus, flac y pcm. Esta variedad garantiza que puedas integrar la voz generada en cualquier flujo de producción, ya sea para edición de video o distribución web.
El formato elegido se especifica en el campo response_format del cuerpo de la petición. Cada formato tiene características técnicas distintas que afectan el tamaño del archivo y la compatibilidad con tus herramientas de postproducción.
Mp3, wav, opus, flac, pcm
Estos cinco formatos cubren las necesidades más comunes. MP3 ofrece compresión con pérdida. WAV y FLAC son sin pérdida, preservando la máxima fidelidad del audio generado. PCM es la forma bruta sin comprimir, y OPUS ofrece una compresión eficiente para web.
- MP3: Compresión con pérdida, tamaño reducido.
- WAV: Audio sin pérdida.
- FLAC: Compresión sin pérdida, archivos ligeros.
- OPUS: Alta eficiencia para transmisión web.
- PCM: Formato de audio sin comprimir.
Selección en campo response_format
Para seleccionar el formato, añade la clave response_format a tu JSON de solicitud. El valor debe ser una de las cinco extensiones admitidas.
Calidad variable según formato
La calidad percibida y el tamaño del archivo varían según la elección. Los formatos sin pérdida como WAV y FLAC mantienen todos los detalles de la síntesis, mientras que MP3 y OPUS reducen el peso del archivo a costa de una pequeña pérdida de datos auditivos.
Límites y rendimiento
La API maneja hasta 60 peticiones por minuto por clave activa (10 antes del primer recargo). Si excedes este límite, recibirás un error 429.
Cada petición acepta un máximo de 4096 caracteres. Para textos más largos, debes dividirlos y unir los archivos de audio resultantes.
60 peticiones por minuto
El límite de velocidad es de 60 solicitudes por minuto por clave API. Antes de tu primer recargo, este límite se reduce a 10 peticiones por minuto para evitar abusos en la prueba gratuita.
4096 caracteres máximo por input
Cada campo input está limitado a 4096 caracteres, incluyendo espacios y puntuación. Si tu guion supera esta longitud, divide el texto en partes más pequeñas y concatena los archivos de audio generados.
Procesamiento secuencial en cola
Las solicitudes se procesan de forma secuencial. En momentos de alta demanda, las peticiones pueden esperar en una cola, lo que aumenta ligeramente el tiempo de generación comparado con el tiempo real de audio.
Códigos de error comunes
La API devuelve códigos de estado HTTP estándar para indicar el resultado de cada solicitud. Es fundamental verificar estos códigos en la respuesta para gestionar correctamente los errores de autenticación, límites de uso o formatos inválidos.
A continuación se detallan los errores más frecuentes que puedes encontrar al integrar el servicio en tu flujo de trabajo.
Error 401 por clave inválida
Este error indica que la clave Bearer proporcionada no es válida o ha caducado. Si emites una nueva clave en el panel, la anterior deja de funcionar inmediatamente.
- Verifica que la cabecera Authorization incluya el prefijo Bearer seguido de tu clave actual.
- Si has renovado tu clave recientemente, asegúrate de actualizarla en tu código.
Error 429 por límite excedido
Se produce al superar los 60 solicitudes por minuto. Si tu aplicación envía peticiones en ráfaga, implementa una lógica de reintentos con retroceso exponencial para evitar bloqueos temporales.
- El límite se aplica por clave API.
- Cuenta caracteres y no solo peticiones para optimizar tu uso.
Errores de formato JSON
La API espera un cuerpo JSON válido con los campos requeridos. Si falta input o voice, o si los tipos de datos no coinciden, la solicitud se rechazará.
- Asegúrate de que input sea una cadena de texto.
- Verifica que voice sea uno de los 8 presets válidos.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Su energía la convierte en una herramienta efectiva para anuncios, introducciones rápidas o contenido que necesita ritmo.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
