Preguntas frecuentes
¿Qué es la base_url?
La base_url es el punto de acceso para las solicitudes HTTP. Para este servicio, debes configurarla en https://api.ak7x.info/v1. Esto permite que las librerías estándar, como las de OpenAI, se conecten correctamente a nuestro endpoint para enviar texto y recibir audio sintetizado.
¿Puedo usar el SDK oficial de OpenAI?
Sí, puedes usar las librerías oficiales de OpenAI. Solo necesitas cambiar la base_url a https://api.ak7x.info/v1 y utilizar tu clave de API de VozNómada. La estructura de las solicitudes es idéntica a la del endpoint de speech de OpenAI, facilitando la integración inmediata.
¿Qué formato devuelve la API?
La API devuelve archivos de audio en los formatos mp3, wav, opus, flac o pcm. Debes especificar el formato deseado en el campo response_format de tu solicitud JSON. Cada archivo generado contiene una marca de agua inaudible que lo identifica como voz sintética.
¿Qué hago si me devuelven un error 429?
El error 429 indica que has excedido el límite de 60 solicitudes por minuto. Espera a que el contador se reinicie o reduce la frecuencia de tus peticiones. Si usas una clave nueva, el límite inicial es de solo 10 solicitudes por minuto hasta el primer recargo.
¿Cuántos caracteres máximos puedo enviar?
Puedes enviar hasta 4096 caracteres por solicitud. Si tu texto es más largo, debes dividirlo en partes 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 permitido por la API.
¿Qué ocurre si el servidor está lento?
Las solicitudes se procesan en cola, una tras otra. Si hay mucha carga, tu petición puede esperar antes de generarse. Para textos largos, la velocidad es aproximadamente de tiempo real, pero las frases cortas pueden tardar unos segundos en completarse debido a este procesamiento secuencial.
¿Cómo se emite una nueva clave?
Puedes emitir una nueva clave de API desde tu cuenta en cualquier momento. Simplemente accede a la sección de configuración de tu API key en el panel de usuario. La nueva clave se activará inmediatamente para tus futuras solicitudes, reemplazando a la anterior.
¿La clave antigua deja de funcionar al instante?
Sí, al generar una nueva clave, la anterior deja de funcionar de forma inmediata. Esto asegura que solo tengas una clave activa por cuenta. Asegúrate de actualizar la variable de entorno o la configuración de tu aplicación con la nueva clave para evitar errores de autenticación.
Primera solicitud
curl
curl https://api.ak7x.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.ak7x.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.ak7x.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 |
Obtención de la clave API
Accede a tu panel desde /get-api-key/ registrándote con Google o con email y contraseña. La clave se genera al instante y el saldo aparece visible junto al ejemplo de curl listo para usar.
Registro con Google
Al registrarte con Google, recibes $0.50 de crédito válido por 7 días, suficiente para unas 50 000 caracteres. Este saldo inicial permite probar la API sin necesidad de tarjeta ni pago inmediato.
- Crédito de prueba automático
- Válido por 7 días
- Sin necesidad de tarjeta
Registro con email
Si prefieres email y contraseña, tu cuenta se crea sin saldo de prueba inicial. Puedes cargar saldo más adelante mediante USDT en la red TRON (TRC-20) para comenzar a generar audio.
- Registro simple con email
- Sin saldo inicial
- Recarga con USDT TRC-20
Gestión de claves
La página de tu panel muestra tu clave activa, el saldo restante y el historial de uso. Puedes emitir una nueva clave en cualquier momento; la anterior deja de funcionar de forma inmediata.
- Clave única por cuenta
- Revocación instantánea
- Panel con métricas claras
Primera petición con curl
Genera audio enviando texto mediante POST a https://api.ak7x.info/v1/audio/speech. El cuerpo JSON incluye el modelo, el texto a sintetizar, la voz deseada y el formato de salida. Los caracteres cuentan como tal, incluyendo espacios y puntuación, con un límite de 4096 caracteres por petición.
Cuerpo JSON
La solicitud debe contener los campos model, input, voice y response_format. Por ejemplo: `{"model": "tts-1", "input": "Bienvenido a este museo", "voice": "aria", "response_format": "mp3"}`.
Parámetros básicos
Usa tts-1 o tts-1-hd. El campo voice acepta valores como aria, nova o atlas. Puedes ajustar la speed entre 0.25 y 4.0.
Respuesta de audio
La respuesta contiene el archivo de audio binario en el formato solicitado. Si la síntesis falla, no se cobra. Los archivos llevan una marca de agua invisible que indica que es voz sintética.
Uso con SDK de OpenAI
Nuestra API sigue el mismo formato de petición que el endpoint de speech de OpenAI, lo que permite reutilizar las librerías oficiales sin adaptar la lógica de tu aplicación. Solo necesitas ajustar la URL base para apuntar a nuestro servicio.
Este enfoque simplifica la integración en apps móviles o dispositivos de visita, ya que puedes usar el mismo código de SDK para generar audioguías turísticas o contenidos narrativos con acentos reales.
Cambio de base_url
Modifica el atributo base_url del cliente de OpenAI para que apunte a https://api.ak7x.info/v1. Esto redirige todas las llamadas al endpoint POST /v1/audio/speech de VozNómada sin cambiar la estructura del cuerpo JSON.
Con este ajuste, tus solicitudes de texto a voz se procesan directamente en nuestra infraestructura, manteniendo la compatibilidad con la forma de petición estándar que ya conoces.
- API base: https://api.ak7x.info/v1
- Endpoint: POST /v1/audio/speech
- Formato: JSON idéntico a OpenAI
Mismas librerías
Utiliza las mismas librerías oficiales de OpenAI que ya tienes instaladas en tu proyecto. No necesitas un SDK propio ni instalar paquetes adicionales específicos de VozNómada.
La compatibilidad es total con los clientes oficiales, lo que facilita la migración o la integración inicial sin aprender una nueva sintaxis de programación.
Configuración simple
Configura tu clave API con el prefijo tts- en la cabecera de autenticación. El código se reduce a inicializar el cliente con la nueva URL base y enviar el texto.
Este flujo directo permite generar audio, ideal para crear audioguías dinámicas sin complicaciones de infraestructura.
Formatos de salida
La API devuelve audio listo para reproducir en el formato que elijas. Puedes elegir entre MP3, WAV u OPUS para equilibrar compatibilidad y tamaño, o usar FLAC y PCM si necesitas máxima fidelidad o procesamiento adicional.
MP3, WAV, OPUS
Estos formatos son ideales para la mayoría de las aplicaciones móviles y web. MP3 ofrece compresión, WAV es sin comprimir y fácil de editar, mientras que OPUS permite un tamaño de archivo muy pequeño manteniendo una calidad clara.
FLAC y PCM
Usa FLAC para audio sin pérdida comprimido, perfecto para archivos de alta calidad que necesitas guardar. PCM es audio sin comprimir sin encabezado, útil si tu herramienta de postproducción requiere un flujo de bits crudo.
Elección por calidad
La calidad de audio depende del modelo seleccionado (tts-1 o tts-1-hd) y no del formato de salida. El formato solo afecta al tamaño del archivo y la compatibilidad del reproductor. Selecciona el que mejor se adapte a tu pipeline de audioguías o app.
- MP3: ideal para apps móviles.
- WAV: estándar para edición simple.
- OPUS: máximo ahorro de espacio.
- FLAC: calidad de estudio sin pérdida.
- PCM: flujo de datos sin encabezado.
Manejo de errores
La API devuelve códigos de estado HTTP estandarizados para indicar el resultado de cada solicitud. Un 200 significa que el audio se generó correctamente, mientras que códigos 4xx indican errores de entrada o autenticación, y 5xx señalan problemas temporales del servidor.
Códigos de estado
Los errores 400 suelen deberse a parámetros inválidos, como un formato de audio no soportado o un texto excesivamente largo. Los 401 indican que la clave API es incorrecta o ha sido revocada. Los 503 sugieren que el servicio está temporalmente saturado; en estos casos, la petición puede esperar en una cola.
- 200: Éxito, audio disponible en la respuesta.
- 400: Error de solicitud, revisar parámetros.
- 401: Autenticación fallida o clave inválida.
- 503: Servicio saturado, reintento sugerido.
Petición fallida gratuita
Si la síntesis falla por un error del servidor o un problema técnico durante el procesamiento, no se te cobra. El importe se devuelve a tu saldo automáticamente. Esto asegura que solo pagas por audioguías o narraciones que se entregan exitosamente a tu aplicación móvil o dispositivo de visita.
Límites de velocidad
Tienes un límite de 60 peticiones por minuto por clave API (o 10 por minuto antes de la primera recarga). Si superas este umbral, la API devuelve un 429. Las peticiones adicionales se procesan en una cola una vez que se libera capacidad, sin perder tu texto ni tu configuración.
- Límite estándar: 60 req/min.
- Límite inicial: 10 req/min.
- Exceso: Código 429 + cola.

Límites y velocidad
Para evitar saturar el servicio, la API permite hasta 60 solicitudes por minuto por clave. Este límite es suficiente para la mayoría de las audioguías y aplicaciones móviles, aunque si superas la cuota, las peticiones adicionales se procesarán en una cola.
60 peticiones por minuto
Cada clave activa tiene un límite de 60 peticiones por minuto. Antes de la primera recarga, este límite es de 10 por minuto. Si excedes la cuota, las solicitudes se encolarán automáticamente sin costo adicional.
Cola de procesamiento
Las peticiones se procesan una tras otra. En momentos de alta demanda, una solicitud puede esperar en cola antes de comenzar. La generación suele ser aproximadamente en tiempo real (25 caracteres por segundo), pero los textos largos pueden tardar unos segundos más.
Texto largo dividido
Cada petición acepta hasta 4096 caracteres. Si tu texto es más extenso, debes dividirlo en partes y unir los archivos de audio resultantes. Esto permite crear audioguías completas sin perder calidad ni precisión en la voz.
Estructura de la petición
La estructura de la petición JSON es directa y sigue el formato estándar de la API. Solo necesitas definir el modelo, el formato de salida y el texto a convertir, asegurando compatibilidad con las librerías existentes.
Modelo tts-1
El campo model acepta dos valores: "tts-1" o "tts-1-hd". Ambos utilizan el mismo motor de síntesis y tienen idéntico precio, por lo que puedes elegirlos indistintamente según tu preferencia sin impacto económico adicional.
Campo voice
Debes especificar una de las ocho voces predefinidas (aria, nova, luna, sage, felix, milo, atlas, orion). Cada una tiene un tono distinto, desde narrativas claras hasta conversaciones amigables, adaptable al idioma del texto o forzado mediante el parámetro language.
Campo input
El texto a sintetizar se envía en el campo input. La API acepta hasta 4096 caracteres por petición. Si tu guion es más largo, tu aplicación debe dividirlo en partes y unir los archivos de audio resultantes.
Autenticación
La autenticación se gestiona exclusivamente mediante una cabecera HTTP estándar. Cada petición debe incluir la clave API para identificar tu cuenta y autorizar el uso del servicio.
Cabecera Bearer
Incluye el encabezado Authorization: Bearer tts-... en cada solicitud POST. Este formato es compatible con la mayoría de las herramientas HTTP y SDKs existentes.
Formato de clave
Las claves comienzan con el prefijo tts- y se generan en tu panel de control. Solo hay una clave activa por cuenta, lo que simplifica la gestión de seguridad.
Revocación inmediata
Puedes emitir una nueva clave en cualquier momento desde la configuración de tu cuenta. La clave anterior deja de funcionar instantáneamente, garantizando que el acceso anterior quede invalidado sin retrasos.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Entender las diferencias de tono es clave para que tu audioguía suene coherente con el espacio físico.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
Fuentes y lecturas adicionales
- Wikipedia
- curl documentation
- Python documentation
- OpenAI API reference: create speech
- Creative Commons Attribution 4.0
- W3C WAI: making audio and video accessible
- Node.js documentation
- LibriVox public-domain audiobooks
- LibriTTS-R paper (arXiv 2305.18802)
- Tether (USDT)
- FFmpeg documentation
- LibriTTS-R corpus (OpenSLR 141)
