Integra nuestra API de texto a voz con esta documentación técnica

Por equipo editorial de VozNómada · Actualizado 2026-11-19

Aquí encontrarás la guía técnica para integrar nuestra API de texto a voz en tus aplicaciones de audioguías para museos o startups de turismo. Esta documentación detalla los endpoints, parámetros y flujos de trabajo necesarios para convertir texto en audio, utilizando el mismo formato que la API de OpenAI para una integración rápida.

El lector aprenderá a gestionar su clave API, configurar el formato de salida y manejar errores comunes. Las explicaciones son prácticas, con ejemplos de código curl y ajustes de velocidad, ideales para desarrolladores que necesitan voz natural sin complicaciones. No asumimos conocimientos previos, pero sí que buscas eficiencia en tus proyectos de audio.

Integra nuestra API de texto a voz con esta documentación técnica

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.mp3

Python (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
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

Obtención de la clave API

Ilustración de onda de sonido para: 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

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

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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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.
Manejo de errores

Límites y velocidad

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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.

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. curl documentation
  3. Python documentation
  4. OpenAI API reference: create speech
  5. Creative Commons Attribution 4.0
  6. W3C WAI: making audio and video accessible
  7. Node.js documentation
  8. LibriVox public-domain audiobooks
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. Tether (USDT)
  11. FFmpeg documentation
  12. LibriTTS-R corpus (OpenSLR 141)

Más en este sitio