Guía de integración y uso de la API de síntesis de voz

Por equipo editorial de AliaVoz · Actualizado 2026-11-19

Esta guía explica cómo integrar nuestra API de texto a voz en aplicaciones móviles para dispositivos Android e iOS. Aquí encontrarás ejemplos concretos de código, la lista de voces disponibles y los parámetros necesarios para generar audio de alta calidad sin depender de grandes plataformas. Es un recurso práctico para desarrolladores que buscan simplicidad y control total sobre la síntesis de voz.

Podrás aprender a gestionar tu clave API, ajustar la velocidad de lectura y manejar errores comunes en producción. La documentación está diseñada para ayudarte a implementar soluciones de audio eficientes, desde frases cortas hasta textos extensos, utilizando estándares compatibles con las herramientas que ya conoces, como el SDK de OpenAI. Todo lo necesario para empezar a desarrollar en minutos.

Guía de integración y uso de la API de síntesis de voz

Preguntas frecuentes

¿Cómo obtengo una clave API?

Regístrate en /get-api-key/ con Google o correo electrónico. Al iniciar sesión, obtienes una clave única con formato Bearer tts-... que puedes regenerar en cualquier momento. La nueva clave invalida inmediatamente a la anterior.

¿Qué es el endpoint /v1/audio/speech?

Es el punto final POST principal para enviar texto y recibir audio. Envías un JSON con campos como model, input, voice y response_format. La API procesa la solicitud y devuelve el archivo de audio generado.

¿Puedo usar el SDK de OpenAI?

Sí, el endpoint tiene la misma forma de solicitud que la API de OpenAI. Solo necesitas cambiar la base_url a https://api.g7777.info/v1 y usar tu clave de API con el SDK oficial de OpenAI.

¿Qué formatos de audio soportan?

Puedes solicitar audio en los formatos mp3, wav, opus, flac o pcm. Estos se especifican en el campo response_format de tu solicitud JSON. El formato seleccionado determina el tipo de archivo que recibirás.

¿Cuál es el límite de caracteres?

Cada solicitud soporta hasta 4096 caracteres en el campo input. Si tu texto excede este límite, debes dividirlo en partes más pequeñas y unir los archivos de audio resultantes para obtener el audio completo.

¿Qué pasa si excedo los límites?

El límite es de 60 solicitudes por minuto por clave (10 req/min antes del primer recargo). Si excedes este límite, las solicitudes adicionales se ponen en cola.

¿Cómo cambio la velocidad del audio?

Usa el campo speed en tu solicitud JSON. El valor debe estar entre 0.25 y 4.0. Un valor de 1.0 es la velocidad normal. Ajusta este parámetro para hacer la voz más rápida o lenta.

¿Se puede especificar un idioma?

Sí, usa el campo language con un código ISO. Si no se especifica, el sistema intenta adivinarlo, pero para textos en latinos distintos al inglés, es recomendable establecerlo manualmente para evitar errores de pronunciación.

¿Qué es la cola de procesamiento?

Las solicitudes se procesan una tras otra. Bajo carga, una solicitud puede esperar en una cola antes de generarse. Esto explica por qué frases cortas tardan unos segundos y textos largos tardan más tiempo en total.

¿Cómo manejo errores en la API?

Si la síntesis falla, la carga se devuelve completamente. No se cobra por solicitudes fallidas. Revisa los códigos de estado HTTP y los mensajes de error en la respuesta para identificar el problema y reintentar si es necesario.

¿Cuántas claves puedo tener?

Solo hay una clave activa por cuenta. Puedes emitir una nueva clave en cualquier momento desde tu panel. La clave anterior deja de funcionar inmediatamente al generar la nueva, asegurando que solo una esté vigente.

¿Se pueden generar audios largos?

Sí, dividiendo el texto en partes de hasta 4096 caracteres. Genera cada parte por separado y luego une los archivos de audio resultantes. Esto permite crear audios de duración ilimitada, aunque el tiempo de generación será proporcional.

¿Qué es el modelo tts-1-hd?

Es uno de los dos modelos disponibles (tts-1 o tts-1-hd). Ambos usan el mismo motor de síntesis y tienen el mismo precio. La elección entre uno u otro no afecta el costo ni la calidad base del audio.

¿Dónde está la documentación técnica?

La documentación técnica completa se encuentra en esta misma página de /docs/. Aquí encontrarás detalles sobre endpoints, parámetros, ejemplos de código y especificaciones de la API para integrar la solución en tus aplicaciones móviles.

Primera solicitud

curl

curl https://api.g7777.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.g7777.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.g7777.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 clave API

Ilustración de onda de sonido para: Obtención de clave API

Para integrar la API, primero crea una cuenta en /get-api-key/ usando Google o correo electrónico. Esta cuenta es específica de g7777.info y no está vinculada a otros servicios.

Una vez registrado, el sistema asigna una clave API única que autenticará tus solicitudes. Es el único requisito para comenzar a generar audio.

Registro de cuenta

Registro de cuenta

Accede a la página de registro y elige entre autenticación con Google o correo electrónico. La cuenta se crea al instante y es válida únicamente para este sitio.

Generación de clave

Generación de clave

Tu clave API se muestra inmediatamente después del registro. Comienza con 'tts-' y es necesaria para todas las solicitudes POST.

Gestión de claves

Puedes emitir una nueva clave en cualquier momento desde tu panel. Al generar una nueva, la anterior deja de funcionar inmediatamente.

  • Solo hay una clave activa por cuenta.
  • La revocación es instantánea.

Primera solicitud

Ilustración de onda de sonido para: Primera solicitud

Una vez obtenida tu clave, puedes generar audio enviando una solicitud POST al endpoint /v1/audio/speech. El cuerpo de la petición debe ser JSON y contener el texto a sintetizar, el modelo y la voz deseada. Esta estructura es idéntica a la de OpenAI, lo que facilita la integración en tus aplicaciones móviles.

La API devuelve el archivo de audio directamente en la respuesta, listo para ser reproducido o almacenado. No necesitas gestionar archivos temporales ni colas externas para esta operación básica.

Ejemplo con cURL

Puedes probar la integración inmediatamente desde tu terminal o script de despliegue. El siguiente comando envía un texto corto y recibe el audio en formato MP3.

```bash curl -X POST https://api.g7777.info/v1/audio/speech \ -H "Authorization: Bearer tts-TU_CLAVE_AQUI" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "Hola mundo", "voice": "aria", "response_format": "mp3" }' \ --output audio.mp3 ```

Parámetros requeridos

Solo necesitas especificar el texto (input), el model (tts-1 o tts-1-hd) y la voice (ej. aria, nova). Puedes añadir language si el texto no es inglés para evitar que el sistema adivine el idioma incorrectamente.

El campo input acepta hasta 4096 caracteres. Si necesitas más texto, deberás dividirlo en partes y unir los archivos resultantes.

  • model: "tts-1" o "tts-1-hd"
  • input: texto máximo 4096 caracteres
  • voice: una de las 8 presets disponibles
  • response_format: mp3, wav, opus, flac o pcm
  • speed: entre 0.25 y 4.0 (opcional)
  • language: código ISO opcional

Formato de respuesta

La respuesta contiene el archivo de audio binario directamente en el cuerpo. Si la síntesis falla, recibirás un código de error y no se te cobrará.

El tiempo de generación es aproximadamente en tiempo real para textos largos, aunque frases cortas pueden tardar unos segundos debido a la cola de procesamiento.

Uso con SDK de OpenAI

Ilustración de onda de sonido para: Uso con SDK de OpenAI

Esta API sigue el mismo formato de solicitud que la endpoint de speech de OpenAI. Esto permite reutilizar las bibliotecas oficiales sin necesidad de un SDK propietario.

El único ajuste necesario es modificar la URL base de la conexión para apuntar a nuestro servicio.

Cambio de base_url

Para conectar tu aplicación, cambia la propiedad base_url de tu cliente a https://api.g7777.info/v1. Esto redirige todas las peticiones al endpoint correcto sin alterar la estructura del cuerpo JSON.

Compatibilidad

Las SDK oficiales de OpenAI para Python, Node.js y otros lenguajes funcionan correctamente. Solo requieren la actualización de la URL base y el uso de tu clave API personalizada.

Ejemplo de código

Usa el cliente estándar de OpenAI, especificando la URL de nuestra API y la autenticación con tu clave.

```python import openai client = openai.OpenAI( base_url="https://api.g7777.info/v1", api_key="tts-tu-clave-aqui" ) ```

Formatos de audio

Ilustración de onda de sonido para: Formatos de audio

La API devuelve audio en formatos estándar compatibles con la mayoría de los reproductores y bibliotecas de audio móviles. La elección del formato afecta directamente el tamaño del archivo y la calidad perceptible del resultado final.

MP3

El formato predeterminado y más ligero. Ideal para aplicaciones móviles donde el ahorro de ancho de banda es prioritario. Ofrece una buena relación entre calidad y tamaño de archivo para la mayoría de los casos de uso.

WAV

Proporciona audio sin pérdida de calidad. Es útil para ediciones posteriores o cuando se necesita fidelidad máxima sin compresión. El tamaño del archivo es considerablemente mayor que el de MP3 o OPUS.

OPUS y FLAC

OPUS ofrece una compresión eficiente con alta calidad, ideal para almacenamiento a largo plazo. FLAC es sin pérdida pero comprimido, manteniendo la calidad original del archivo WAV con un tamaño menor.

Manejo de errores

Ilustración de onda de sonido para: Manejo de errores

Cuando la síntesis falla, no se cobra. El API devuelve un código de error y el carácter no se descuenta de tu saldo, lo que elimina el riesgo de perder créditos por fallos técnicos momentáneos.

Códigos de estado

Un error 4xx indica problemas con la solicitud, como una clave inválida o texto excedente. Un 5xx señala fallos internos temporales del servicio. En ambos casos, la respuesta JSON detalla la causa específica.

  • 401: Clave de autorización incorrecta o expirada.
  • 429: Límite de velocidad (60 req/min) excedido.
  • 500-503: Fallos internos del servidor o cola saturada.

Mensajes de error

La respuesta JSON incluye un campo error con un message descriptivo y un code técnico. Usa estos valores para registrar el fallo en tu log y ajustar la lógica de tu app sin adivinar la causa.

  • mensaje: Descripción legible del problema.
  • code: Identificador único para depuración (ej. "rate_limit").

Reintento automático

Implementa un reintorno exponencial simple para errores 5xx o 429. Como las solicitudes se procesan en cola, esperar unos segundos antes de reintentar suele resolver el problema sin sobrecargar la API.

Manejo de errores

Límites de velocidad

Ilustración de onda de sonido para: Límites de velocidad

Tu clave API tiene un límite de 60 solicitudes por minuto. Si tu aplicación móvil genera audio de forma simultánea, es importante planificar la concurrencia para evitar colas.

60 solicitudes/minuto

El límite se aplica por clave activa. Si superas las 60 solicitudes en un minuto, las peticiones adicionales se ponen en cola hasta que haya capacidad disponible (o 10 req/min antes del primer recargo).

  • 10 solicitudes/minuto antes del primer recargo

Cola de procesamiento

Las solicitudes se procesan en orden. Durante picos de tráfico, la generación puede tardar más de lo habitual, especialmente con textos largos que requieren división en fragmentos.

Uso en producción

Para apps móviles, considera implementar un reintentó exponencial con retroceso para manejar retrasos en la cola. Monitorea el uso para mantener un flujo constante de audio sin sobrecargar la API.

  • Implementa reintentos con backoff

Voces y modelos

Ilustración de onda de sonido para: Voces y modelos

La API ofrece ocho voces predefinidas, seleccionadas por su claridad y versatilidad para aplicaciones móviles. Estas voces están basadas en grabaciones con licencia y pueden hablar cualquiera de los 23 idiomas soportados, incluyendo español, inglés, japonés y alemán.

Puedes elegir entre voces femeninas como Aria o Nova, y masculinas como Felix o Atlas. Cada una tiene un tono distinto, desde narrador claro hasta conversacional amigable, ideal para diferentes contextos de tu aplicación.

Lista de voces

Disponemos de ocho voces distintas que cubren una amplia gama de estilos. Todas pueden pronunciar cualquier idioma de nuestra lista sin necesidad de cambiar de modelo.

Las voces femeninas incluyen Aria (narradora clara), Nova (alegre), Luna (suave) y Sage (instruccional). Las masculinas son Felix (energética), Milo (conversacional), Atlas (neutral) y Orion (profunda).

  • Aria: narradora cálida y clara
  • Nova: brillante y animada
  • Luna: suave, ideal para historias
  • Sage: calma y educativa
  • Felix: enérgica, buena para promos
  • Milo: amigable y cercana
  • Atlas: neutral, estilo noticias
  • Orion: profunda, documental

Modelos tts-1

El sistema utiliza dos variantes del motor de síntesis: tts-1 y tts-1-hd. Ambas usan el mismo motor de inteligencia artificial y tienen idéntico precio por carácter.

Ambos modelos usan el mismo motor y tienen idéntico precio por carácter.

Ajuste de velocidad

Puedes controlar la velocidad de la voz entre 0.25x y 4.0x. Esto es útil para adaptar el audio a la duración deseada en tu interfaz móvil.

Ajustar la velocidad no afecta el precio ni la calidad de la síntesis, solo la duración final del archivo de audio generado.

Ejemplos completos

Ilustración de onda de sonido para: Ejemplos completos

Estos ejemplos muestran cómo usar la API para casos cotidianos. Desde una frase corta hasta textos extensos o con idiomas específicos, el formato de solicitud es consistente y sencillo de implementar en tu app móvil.

Cada caso respeta los límites de 4096 caracteres por petición y utiliza las voces disponibles para garantizar una integración fluida sin dependencias externas complejas.

Texto simple

Para frases cortas, envía el texto directamente. La API responde con el archivo de audio en el formato elegido (mp3, wav, opus, flac o pcm). Recuerda que las solicitudes fallidas son gratuitas y el saldo se devuelve íntegramente.

  • Modelo: tts-1
  • Voz: nova
  • Formato: mp3

Texto largo

Si tu texto supera los 4096 caracteres, debes dividirlo en partes más pequeñas. Genera el audio para cada fragmento por separado y luego une los archivos resultantes. Esto asegura que cada solicitud se procese correctamente sin exceder el límite.

Idioma específico

Aunque la API detecta el idioma por defecto, es recomendable establecer el parámetro language explícitamente para textos en latín que no sean inglés. Esto evita confusiones y mejora la precisión de la síntesis en los 23 idiomas soportados.

  • Código ISO: es, fr, de, etc.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. La simplicidad de la integración REST permite a desarrolladores freelance generar audio rápidamente sin configurar infraestructura adicional.

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. TRON developer hub: TRC-20
  3. Creative Commons Attribution 4.0
  4. curl documentation
  5. ISO 639 language codes
  6. LibriTTS-R corpus (OpenSLR 141)
  7. Tether (USDT)
  8. Python documentation
  9. Node.js documentation
  10. openai-node on GitHub
  11. IETF RFC 7845: Ogg Opus
  12. MDN: Web Speech API

Más en este sitio