Documentación Técnica de la API de Síntesis de Voz

Por Equipo editorial de AudioClaro · Actualizado 2026-11-19

Esta documentación técnica detalla la integración de la API de síntesis de voz de AudioClaro, diseñada específicamente para desarrolladores independientes que construyen aplicaciones móviles en Android y otras plataformas. Aquí encontrará la estructura exacta de las solicitudes, los parámetros disponibles y los formatos de audio soportados para implementar voz sintética sin gestión de infraestructura adicional.

El contenido cubre desde la autenticación mediante tokens Bearer hasta la implementación de ejemplos prácticos con cURL y el SDK oficial de OpenAI. Se explican los límites de tasa, los modelos tts-1 y tts-1-hd, así como el manejo de errores, proporcionando toda la información necesaria para una integración técnica precisa.

Documentación Técnica de la API de Síntesis de Voz

Preguntas frecuentes

¿Cómo se obtiene la clave API?

Regístrese en /get-api-key/ con Google o correo electrónico. La página muestra la clave activa, el saldo y un ejemplo curl listo para usar. Cada cuenta tiene una clave activa por sitio, que puede renovarse en cualquier momento.

¿Qué es el campo base_url?

Es el punto de conexión principal: https://api.playuoo.info/v1. Configure este valor en su cliente HTTP o SDK para que las solicitudes POST a /audio/speech y GET a /voices se dirijan correctamente a la API de AudioClaro.

¿Se puede usar el SDK de OpenAI?

Sí. Los SDK oficiales de OpenAI funcionan modificando el base_url a https://api.playuoo.info/v1 y utilizando la clave de API de AudioClaro. Esto permite integrar la síntesis de voz en aplicaciones Android con la misma estructura de código que usaría con OpenAI.

¿Cuántas solicitudes fallidas son gratis?

Todas las solicitudes fallidas son gratuitas. Si la síntesis falla, el cargo se devuelve íntegramente. Solo se cobran las solicitudes que generan audio correctamente, a razón de $0.01 por cada 1.000 caracteres procesados.

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

Es un modelo de alta definición disponible junto con tts-1. Ambos utilizan el mismo motor y tienen el mismo precio. Puede elegir cualquiera de los dos según sus necesidades de calidad sin incurrir en costos adicionales por modelo.

¿Cómo se ajusta la velocidad del audio?

Utilice el campo speed en la solicitud JSON. El valor debe estar entre 0.25 y 4.0. Este parámetro permite acelerar o ralentizar la voz sintética para adaptarse al ritmo de su aplicación móvil sin modificar el texto de entrada.

¿Qué ocurre si excedo el límite de tasa?

El límite es de 60 solicitudes por minuto por clave (10 antes del primer recargo). Si excede este límite, las solicitudes adicionales recibirán un error de límite de tasa hasta que el periodo se reinicie o complete la cola de procesamiento.

¿Se pueden enviar textos largos?

Sí, pero debe dividir el texto en partes de hasta 4096 caracteres por solicitud. Luego, debe unir los archivos de audio generados manualmente en su aplicación. Cada solicitud tiene un límite estricto de caracteres para garantizar el procesamiento correcto.

¿Cómo se maneja el error 429?

El código 429 indica que ha excedido el límite de 60 solicitudes por minuto. Implemente una lógica de reintento con retroceso exponencial en su cliente Android. Espere a que la cuota se restablezca antes de reenviar la solicitud pendiente.

¿Es necesario instalar un SDK propio?

No. No ofrecemos un SDK propio. Puede usar el SDK de OpenAI con el base_url configurado o realizar solicitudes HTTP directas. Esto facilita la integración en Android usando bibliotecas estándar como OkHttp o Retrofit sin dependencias adicionales específicas.

¿Qué formato es mejor para Android?

Los formatos soportados son mp3, wav, opus, flac y pcm. Para Android, mp3 o opus son formatos adecuados por su equilibrio entre calidad y tamaño de archivo. wav y flac ofrecen alta fidelidad pero consumen más almacenamiento en el dispositivo.

¿Cómo se revoca una clave API?

Emita una nueva clave desde la página de su cuenta. La clave anterior deja de funcionar inmediatamente al generar la nueva. Esto invalida cualquier acceso no deseado sin necesidad de esperar a que expire automáticamente, garantizando seguridad inmediata.

¿Se soporta la codificación UTF-8?

Sí, el cuerpo JSON de la solicitud utiliza codificación UTF-8 estándar. Esto permite el envío correcto de caracteres especiales y textos en los 23 idiomas soportados, incluyendo árabe, chino, japonés y coreano, sin necesidad de codificaciones adicionales.

¿Dónde se documentan los errores?

Los códigos de error estándar HTTP se devuelven en la respuesta. Consulte la documentación técnica en /docs/ para ver los detalles específicos de cada código, como 401 para claves inválidas o 429 para límites de tasa excedidos.

Primera solicitud

curl

curl https://api.playuoo.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.playuoo.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.playuoo.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

Autenticación

Ilustración de onda de sonido para: Autenticación

La autenticación se realiza mediante el encabezado Authorization: Bearer <your-api-key>. Cada cuenta dispone de una única clave activa que identifica la solicitud ante el endpoint https://api.playuoo.info/v1.

La clave se obtiene al registrarse en /get-api-key/. Es necesario incluirla en cada petición para verificar el saldo y los límites de tasa.

Uso del token Bearer

Uso del token Bearer

El token debe enviarse en el campo de cabecera Authorization de cada solicitud HTTP. El formato estricto es Bearer <clave>, sin comillas adicionales alrededor del token.

  • Incluir siempre el prefijo "Bearer" seguido de un espacio.
  • Verificar que no haya espacios extra en la cadena de la clave.
  • Usar HTTPS para garantizar la transmisión segura de la credencial.

Generación de clave API

Generación de clave API

La clave se genera al crear una cuenta en la página /get-api-key/. Se puede usar inicio de sesión con Google o correo electrónico con contraseña.

  • Acceder a /get-api-key/ tras el registro.
  • Copiar la clave mostrada en el panel de control.
  • Guardar la clave en variables de entorno para entornos de producción.

Revocación inmediata de claves

Cualquier nueva clave generada invalida instantáneamente a la anterior. No existe un período de transición; la clave vieja deja de funcionar al momento de la emisión de la nueva.

  • Generar una nueva clave para revocar la actual.
  • Actualizar la variable de entorno en los dispositivos Android inmediatamente si la aplicación utiliza la clave antigua.
  • No es posible revocar manualmente sin generar una nueva.

Endpoint principal

Ilustración de onda de sonido para: Endpoint principal

El servicio de síntesis de voz opera mediante un único punto de entrada HTTP. Esta arquitectura simplifica la integración en aplicaciones Android, eliminando la necesidad de gestionar múltiples rutas o versiones de endpoints. Los desarrolladores envían el texto a procesar y reciben directamente el archivo de audio generado.

URL del servicio de síntesis

Todas las solicitudes de generación deben dirigirse a la siguiente dirección base:

https://api.playuoo.info/v1/audio/speech

Método POST requerido

El servicio exige el método HTTP POST. Las solicitudes GET no son válidas para generar audio, aunque se utilizan para consultar metadatos como la lista de voces disponibles o el estado de los modelos en el endpoint /v1/voices.

Estructura del cuerpo JSON

El cuerpo de la solicitud debe ser un objeto JSON que contenga los parámetros necesarios para la síntesis. Es obligatorio especificar el modelo, el texto de entrada (máximo 4096 caracteres) y la voz deseada. Opcionalmente, se pueden ajustar la velocidad y el formato de salida.

Modelos de voz

Ilustración de onda de sonido para: Modelos de voz

La API ofrece dos modelos de motor de síntesis disponibles bajo los identificadores tts-1 y tts-1-hd. Ambos utilizan la misma infraestructura de generación de audio, lo que garantiza una coherencia técnica en la salida independientemente de la selección.

La elección entre modelos depende exclusivamente de la prioridad entre latencia y complejidad espectral del audio, manteniendo un formato de respuesta uniforme para la integración en aplicaciones Android.

Modelo tts-1 estándar

El modelo tts-1 es la configuración base para la síntesis de voz. Proporciona audio de calidad adecuada para la mayoría de las aplicaciones móviles y narrativas.

Modelo tts-1 hd

El modelo tts-1-hd activa la misma motorización subyacente pero bajo la etiqueta de alta definición. Es adecuado cuando se requiere una fidelidad espectral superior.

Técnicamente comparte el mismo motor que tts-1, diferenciándose principalmente en la percepción de calidad del audio generado.

Diferencias de precio y calidad

A diferencia de otros proveedores, ambos modelos tienen exactamente el mismo precio por carácter. No existe penalización ni bonificación económica al seleccionar tts-1-hd frente a tts-1.

La decisión es puramente técnica: se selecciona tts-1-hd cuando la claridad del audio es prioritaria, sin impacto en la facturación ni en la estructura del cuerpo JSON.

Parámetros de entrada

Ilustración de onda de sonido para: Parámetros de entrada

La API acepta texto sin formato mediante el campo input, con un límite estricto de 4096 caracteres por solicitud. Los espacios y la puntuación se cuentan como caracteres válidos para el cálculo de la cuota. Para textos extensos, la aplicación cliente debe dividir la entrada y unir los archivos de audio resultantes.

Campo input para el texto

El campo input recibe la cadena de caracteres a sintetizar. Si el texto excede 4096 caracteres, la solicitud fallará. La aplicación debe implementar la lógica de chunking o dividir el texto en partes manejables antes de enviarlas al endpoint.

Selección de voice preset

Seleccione una de las 8 voces predefinidas mediante el campo voice. Las opciones incluyen estilos narrativos, institucionales o publicitarios como aria, nova o atlas. Cada voz tiene un tono específico de comunicación.

  • aria: narradora clara y cálida
  • nova: tono brillante y dinámico
  • atlas: neutral y periodístico
  • miló: conversacional y amigable

Ajuste de velocidad y idioma

El parámetro speed permite ajustar la velocidad de reproducción entre 0.25 y 4.0. El campo language es opcional; si se omite, el sistema detecta el idioma basándose en el script, asumiendo inglés por defecto para texto en latín. Especificar el código ISO mejora la precisión en idiomas no ingleses.

Formatos de salida

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

La API permite especificar el formato de salida mediante el parámetro response_format. Las opciones disponibles son mp3, wav, opus, flac y pcm, adaptándose a distintas necesidades de compresión y compatibilidad en entornos móviles.

Configuración response_format

Incluya el campo response_format en el cuerpo JSON de la solicitud POST. El valor debe ser una de las cadenas permitidas: "mp3", "wav", "opus", "flac" o "pcm".

Ventajas del formato MP3

El formato MP3 ofrece una buena relación entre tamaño de archivo y calidad para la mayoría de las aplicaciones Android. Su compresión con pérdida reduce significativamente el uso de datos móviles del usuario final sin afectar notablemente la inteligibilidad del habla sintetizada.

Uso de WAV y OPUS

Utilice WAV para obtener audio sin pérdida, ideal para pruebas de calidad o procesamiento posterior. El formato OPUS es adecuado cuando se requiere alta eficiencia de compresión.

Formatos de salida

Ejemplo con cURL

Ilustración de onda de sonido para: Ejemplo con cURL

La integración básica mediante cURL valida la conectividad con el endpoint de síntesis. Este método permite verificar la respuesta de audio sin depender de librerías externas ni del SDK de OpenAI.

Código de solicitud básica

Utilice la siguiente estructura JSON para enviar texto al modelo tts-1. Reemplace YOUR_API_KEY con su credencial activa y ajuste los parámetros de voz y formato según sus necesidades de compilación para Android.

  • curl -X POST https://api.playuoo.info/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Texto de prueba", "voice": "aria", "response_format": "mp3"}'

Copia y pega en terminal

Pegue el comando directamente en su entorno de desarrollo. Asegúrese de que la clave comience con "tts-" y que el texto input no exceda los 4096 caracteres para evitar errores de validación.

Verificación de respuesta exitosa

Una respuesta correcta devuelve un archivo binario de audio en el formato especificado. Si el código de estado es 200, el archivo generado está listo para ser incrustado en su aplicación móvil.

Uso con SDK de OpenAI

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

La API sigue el formato de solicitud de OpenAI, lo que permite a los desarrolladores de Android reutilizar las librerías oficiales sin escribir lógica de red personalizada. Solo es necesario ajustar la configuración de conexión para apuntar a nuestra infraestructura.

Este enfoque reduce la fricción de integración, permitiendo mantener el código de síntesis de voz limpio y compatible con los patrones de desarrollo estándar de la industria.

Modificación del base_url

Configure la URL base de su cliente SDK a https://api.playuoo.info/v1. Esto redirige todas las llamadas a nuestro endpoint de síntesis manteniendo la estructura JSON nativa.

El cliente seguirá utilizando los métodos estándar de la biblioteca para procesar las respuestas y manejar errores HTTP.

Reutilización de la clave API

Utilice la misma clave API generada en su panel de cuenta para la autenticación mediante el encabezado Authorization: Bearer. No se requiere un ID de proyecto adicional ni configuración de credenciales complementarias.

La clave garantiza que el consumo de caracteres se registre correctamente en su saldo y balance.

Compatibilidad con librerías oficiales

Las bibliotecas oficiales de OpenAI funcionan sin modificaciones en su lógica de negocio. Simplemente cambie la URL base y mantenga el uso del método speech.

Esto facilita la migración o el uso simultáneo de otros servicios que sigan este estándar.

Límites y errores

Ilustración de onda de sonido para: Límites y errores

La API limita la generación a 60 solicitudes por minuto por clave activa, con un umbral inicial de 10 rpm hasta el primer recargo. Las peticiones se procesan en cola secuencial; bajo carga, la latencia puede superar el tiempo real de síntesis.

Las respuestas incluyen códigos de estado HTTP estándar para indicar éxito o fallo. Las solicitudes fallidas no generan cargo y el saldo se restaura automáticamente.

Límite de 60 solicitudes por minuto

El límite estricto de 60 peticiones por minuto se aplica por clave API. Antes del primer recargo, el umbral es de 10 rpm. Si la velocidad de generación es aproximadamente real (25 caracteres/segundo), el límite permite sintetizar texto considerable sin bloqueos.

  • 60 req/min tras verificación.
  • 10 req/min antes del primer recargo.
  • Cola secuencial bajo carga.

Código de estado HTTP

El código 200 indica audio generado exitosamente. Los códigos de error (4xx, 5xx) informan sobre fallos en la síntesis o autenticación. En caso de error, no se descuenta saldo.

Manejo de excepciones en código

Implemente lógica de reintento para manejar latencia variable. Verifique el estado de la respuesta antes de parsear el audio binario. Asegure que el cliente de red maneje timeouts superiores a 10 segundos para textos largos.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Esto permite rotar credenciales comprometidas sin impacto en la infraestructura, asegurando que solo las claves activas realicen peticiones.

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. openai-node on GitHub
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. W3C WAI: making audio and video accessible
  5. LibriTTS-R corpus (OpenSLR 141)
  6. Python documentation
  7. openai-python on GitHub
  8. LibriVox public-domain audiobooks
  9. FFmpeg documentation
  10. curl documentation
  11. MDN: Web Speech API
  12. OpenAI API reference: create speech

Más en este sitio