Preguntas frecuentes
¿Cómo obtengo una clave API?
Regístrate en /get-api-key/ con Google o correo electrónico. El sistema genera una clave Bearer única. Si usas Google, recibes $0.50 de prueba. Con email/password, el saldo inicia en cero. La clave se muestra en el panel de control junto con el saldo y el historial de uso.
¿Qué modelo debo usar?
Elige entre "tts-1" o "tts-1-hd". Ambos utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. No hay diferencia técnica en la calidad del audio entre ambos modelos, solo en el identificador que envías en el campo model de tu solicitud JSON.
¿Puedo usar el SDK de OpenAI?
Sí. La API tiene la misma forma de solicitud que el endpoint de speech de OpenAI. Solo necesitas cambiar la base_url a https://api.gf66.info/v1 y usar tu clave de NarradorIA. Las bibliotecas oficiales de OpenAI funcionan directamente sin modificaciones adicionales en el código.
¿Cuál es el límite de caracteres?
Cada solicitud POST acepta un máximo de 4096 caracteres en el campo input. Si tu texto es más largo, debes dividirlo en fragmentos 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.
¿Qué formatos de audio soporta?
Puedes solicitar audio en los formatos mp3, wav, opus, flac o pcm mediante el campo response_format. Estos son los únicos formatos disponibles. No hay soporte para streaming ni formatos de audio personalizados más allá de esta lista estándar especificada en la documentación técnica.
¿Cómo cambio la velocidad de voz?
Ajusta el parámetro speed en tu solicitud JSON. El rango aceptado es de 0.25 a 4.0. Un valor de 1.0 es la velocidad normal. Los valores menores ralentizan la voz y los mayores la aceleran. El cambio se aplica en tiempo de generación del audio.
¿Qué pasa si excedo el límite?
El límite es de 60 solicitudes por minuto por clave. Si superas este límite, las solicitudes se procesarán en cola. Las solicitudes fallidas (por ejemplo, por error) son gratuitas; las solicitudes en cola se procesan cuando hay capacidad.
¿Por qué falla mi solicitud?
Las fallas pueden deberse a errores de formato JSON, claves inválidas o exceder los 4096 caracteres. Si la síntesis falla, el cargo se devuelve íntegramente. Verifica que tu clave Bearer sea correcta y que el texto input no contenga caracteres no permitidos o exceda el límite.
¿Es compatible con Python?
Sí, usando la biblioteca oficial de OpenAI para Python. Configura la variable de entorno o el parámetro base_url hacia https://api.gf66.info/v1. La biblioteca manejará la autenticación y la serialización JSON automáticamente. Es la forma recomendada para integraciones rápidas en entornos de desarrollo Python.
¿Necesito SDK propio?
No. No tenemos un SDK propietario. Utiliza el SDK de OpenAI o realiza solicitudes HTTP directas. La estructura de la solicitud es idéntica a la de OpenAI, lo que permite usar cualquier cliente HTTP estándar o las bibliotecas oficiales de terceros sin adaptación compleja.
¿Cómo rotar mi clave?
Desde tu panel de control en /get-api-key/, emite una nueva clave. La clave antigua deja de funcionar inmediatamente. No hay período de transición. Asegúrate de actualizar tu aplicación con la nueva clave Bearer antes de que expire la sesión actual si dependes de la autenticación.
¿Qué es el endpoint /v1/voices?
Es un endpoint GET que devuelve la lista de voces disponibles, idiomas soportados, formatos de audio y precios. Puedes consultar este punto para obtener los identificadores válidos para el campo voice y verificar la disponibilidad de idiomas como español, inglés o japonés antes de generar audio.
¿Los errores devuelven audio?
No. Si la solicitud falla, no se genera archivo de audio y no se cobra. La respuesta contiene un código de estado HTTP y un mensaje de error JSON. Solo las solicitudes exitosas devuelven el archivo de audio binario.
¿Puedo usar HTTPS?
Sí, todas las solicitudes deben realizarse mediante HTTPS. La URL base es https://api.gf66.info/v1. El protocolo HTTPS asegura la transmisión segura de tu texto y la autenticación mediante la clave Bearer. No se soporta conexión HTTP sin cifrar para la producción en entorno real.
Primera solicitud
curl
curl https://api.gf66.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.gf66.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.gf66.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 API de NarradorIA utiliza autenticación basada en tokens Bearer para garantizar que cada solicitud de síntesis de voz provenga de una cuenta verificada. Para consumir el endpoint de audio, debes incluir tu clave API en el encabezado de la petición HTTP.
Clave Bearer
Envía tu clave en el encabezado de autorización: Authorization: Bearer tts-tu-clave-aqui. Esta clave es única por cuenta y debe mantenerse privada para evitar el uso no autorizado de tu saldo.
Un solo clave activa
Cada cuenta mantiene exactamente una clave activa. Si se emite una nueva, la anterior deja de funcionar inmediatamente. Esto simplifica la gestión de accesos en tus scripts de automatización para TikTok o Reels.
Rotación de claves
Puedes generar una nueva clave en cualquier momento desde tu panel de control. La transición es instantánea: la clave vieja se invalida al momento de crear la nueva, asegurando que solo uses la versión actual.
Endpoint principal
El punto de entrada principal para generar audio es la ruta POST /v1/audio/speech. Este endpoint acepta texto y devuelve el archivo de audio sintetizado en el formato solicitado. Es el único mecanismo para obtener audio bajo demanda mediante la API de NarradorIA.
La solicitud debe enviarse como un cuerpo JSON que contiene los parámetros necesarios para la síntesis. La respuesta es un archivo de audio binario que se puede guardar directamente o reproducir en aplicaciones web y móviles.
POST /v1/audio/speech
Envía una solicitud HTTP POST a la ruta /v1/audio/speech. La API procesa el texto y devuelve el archivo de audio binario en la respuesta. Las solicitudes se procesan secuencialmente, por lo que bajo carga pueden entrar en una cola de espera.
Cuerpo JSON
El cuerpo de la solicitud debe ser un objeto JSON válido. Debes incluir el campo 'input' con el texto a sintetizar (máximo 4096 caracteres), 'model' para seleccionar la calidad, 'voice' para elegir el preset y 'response_format' para definir el contenedor de audio.
- input: texto a convertir (string)
- model: 'tts-1' o 'tts-1-hd' (string)
- voice: uno de los 8 presets disponibles (string)
- response_format: 'mp3', 'wav', 'opus', 'flac' o 'pcm' (string)
- speed: velocidad entre 0.25 y 4.0 (number, opcional)
- language: código ISO opcional para forzar el idioma
Modelos tts-1 y tts-1-hd
El parámetro 'model' acepta dos valores: 'tts-1' y 'tts-1-hd'. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio. La diferencia principal radica en la calidad de procesamiento del audio. Para la mayoría de los videos para redes sociales, 'tts-1' es suficiente. 'tts-1' y 'tts-1-hd' utilizan el mismo motor y tienen el mismo precio.
Parámetros de entrada
La API acepta texto plano como entrada principal, con un límite estricto de 4096 caracteres por solicitud. Este límite incluye espacios y puntuación. Para textos más extensos, se recomienda dividir la entrada en fragmentos manejables y unir los archivos de audio resultantes en el cliente.
Input de texto
El campo input acepta cualquier cadena de texto válida hasta 4096 caracteres. Cada carácter, incluyendo espacios y signos de puntuación, cuenta para el cálculo de caracteres y facturación. Si el texto excede el límite, la API devolverá un error; no se realiza división automática.
- Máximo 4096 caracteres por request.
- Espacios y puntuación cuentan como caracteres.
- Texto plano, sin etiquetas SSML.
Voz seleccionada
Selecciona una de las 8 voces predefinidas usando el campo voice. Cada voz tiene un timbre distintivo: femenino (aria, nova, luna, sage) o masculino (felix, milo, atlas, orion). La voz no está ligada a un idioma específico; cualquier voz puede pronunciar cualquiera de los 23 idiomas soportados si se especifica el language correcto.
- 8 voces disponibles (aria, nova, luna, sage, felix, milo, atlas, orion).
- Voces independientes del idioma.
- Sin clones personalizados ni voces propias.
Velocidad y idioma
El parámetro speed ajusta la velocidad de narración entre 0.25 y 4.0. El valor por defecto es 1.0. El campo language es opcional; si no se proporciona, el sistema intenta adivinar el idioma basándose en el script (el texto en latín se asume como inglés por defecto). Para texto en latín no inglés, establece language explícitamente.
- Velocidad: 0.25 a 4.0.
- Idioma: ISO code (opcional).
- Default: inglés para texto en latín.
Formatos de respuesta
La API devuelve el archivo de audio generado directamente en el cuerpo de la respuesta HTTP. No hay pasos adicionales ni descargas separadas; el binario llega inmediatamente después de la solicitud POST.
El formato se controla exclusivamente mediante el parámetro response_format. Esto permite optimizar el tamaño del archivo o la compatibilidad con tu pipeline de edición de video para TikTok sin conversiones externas.
MP3, WAV, OPUS
MP3 es el estándar para la mayoría de los editores de video. WAV ofrece calidad sin pérdida y es compatible nativamente con la mayoría de software de edición profesional. OPUS proporciona una compresión eficiente para redes móviles.
- MP3: equilibrado entre tamaño y calidad.
- WAV: sin pérdida, mayor tamaño.
- OPUS: alta compresión.
FLAC y PCM
FLAC es una compresión sin pérdida, útil si necesitas re-encodificar el audio sin degradación adicional. PCM es audio sin comprimir, ideal para pruebas técnicas o integración directa con sistemas de audio profesional.
Audio binario
La respuesta contiene el archivo de audio crudo. No se incluye metadatos JSON dentro del cuerpo cuando se solicita un formato de audio. Para depurar, inspecciona el encabezado Content-Type de la respuesta.
- Contenido: archivo de audio puro.
- Encabezado: Content-Type indica el formato.
Ejemplo con curl
Utiliza curl para enviar texto directamente a la API de NarradorIA. Este método es ideal para pruebas rápidas o integraciones simples sin dependencias externas.
Comando básico
Envía una solicitud POST al endpoint de síntesis. Reemplaza TU_API_KEY con tu clave única y ajusta los parámetros según tu necesidad.
- Endpoint: https://api.gf66.info/v1/audio/speech
- Método: POST
- Formato: JSON
Cuerpo JSON
El cuerpo de la solicitud debe incluir el modelo, el texto a sintetizar y la voz deseada. El texto tiene un límite de 4096 caracteres.
Respuesta esperada
La API devuelve el archivo de audio binario en el formato solicitado (mp3, wav, etc.). Si la síntesis falla, recibirás un código de error con el motivo.

Uso con SDK de OpenAI
La API de NarradorIA mantiene la misma estructura de solicitud que el endpoint de OpenAI, lo que permite reutilizar el código existente sin modificaciones mayores. Solo es necesario ajustar la URL base de la conexión para apuntar a los servidores de gf66.info.
Este enfoque elimina la necesidad de aprender una sintaxis específica o mantener una librería propia. Los desarrolladores pueden integrar la síntesis de voz en sus flujos de trabajo actuales con mínimos cambios de infraestructura.
Cambiar base_url
Configura la variable de entorno OPENAI_BASE_URL o establece base_url explícitamente en tu cliente SDK para que apunte a https://api.gf66.info/v1. Esta dirección reemplaza el punto final estándar de OpenAI.
Asegúrate de que la versión del SDK sea compatible con la estructura de parámetros de la API v1. La autenticación sigue requiriendo el encabezado Authorization: Bearer con tu clave única de NarradorIA.
- URL: https://api.gf66.info/v1
- Encabezado: Authorization: Bearer <tu-clave>
Mismo código
Los parámetros model, input, voice, response_format y speed se envían exactamente igual que en la implementación original de OpenAI. No se requieren adaptadores de datos ni transformación de payloads.
Puedes usar cualquier lenguaje soportado por el SDK oficial (Python, Node.js, etc.). La lógica de manejo de respuestas binarias y errores permanece idéntica, facilitando la migración o el uso simultáneo.
Compatibilidad total
El endpoint POST /v1/audio/speech es completamente compatible con la firma de la API de OpenAI. Esto garantiza que las librerías de cliente estándar funcionen sin parches adicionales.
No necesitas instalar paquetes específicos de NarradorIA. La integración se logra únicamente cambiando la configuración de conexión, manteniendo la estabilidad de tus dependencias actuales.
Límites y rate limiting
La API aplica un límite global de 60 solicitudes por minuto por clave API. Este límite se mantiene constante independientemente del modelo seleccionado (tts-1 o tts-1-hd). Para gestionar textos largos, se recomienda dividirlos en fragmentos de máximo 4096 caracteres y unir los archivos de audio resultantes.
60 req por minuto
Cada clave activa permite un máximo de 60 peticiones por minuto. Este límite se aplica a la suma de todas las solicitudes enviadas con esa clave, sin importar el formato o la velocidad configurados.
10 req iniciales
Al crear una cuenta nueva, el límite inicial es de 10 solicitudes por minuto. Este umbral se eleva automáticamente a 60 req/min tras la primera recarga de saldo.
- Límite base: 10 req/min.
- Recarga mínima: $5 USDT (TRC-20).
- Actualización automática tras el pago.
Cola de procesamiento
Las solicitudes se procesan secuencialmente. Las solicitudes se procesan secuencialmente, por lo que bajo carga pueden entrar en una cola de espera. Esto puede aumentar la latencia total, especialmente en textos extensos.
Errores comunes
Los errores de API son comunes y generalmente fáciles de resolver. Esta sección cubre los casos más frecuentes que encontrarás al integrar NarradorIA en tu flujo de trabajo para generar voz para TikTok o Reels.
Error 401
Significa que tu clave Bearer es inválida o ha sido revocada. Verifica que estés enviando el prefijo "Bearer " antes de la clave. Si rotaste tu clave en el panel, la anterior deja de funcionar inmediatamente.
Error 429
Indica que has excedido el límite de 60 solicitudes por minuto. Si es una cuenta nueva, el límite inicial es de 10 req/min. El servidor rechazará peticiones adicionales hasta que el contador se reinicie.
Texto demasiado largo
El campo input acepta máximo 4096 caracteres. Si tu guion para un Short excede este límite, la API rechazará la solicitud. Debes dividir el texto en partes más pequeñas y unir los archivos de audio resultantes.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. El resultado se guarda localmente para su uso en tus videos.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
