Documentación técnica de la API de texto a voz

Por Equipo editorial de VozFlujo · Actualizado 2026-11-18

Esta documentación técnica está diseñada para equipos de desarrollo de aplicaciones móviles que necesitan integrar voces naturales mediante una API REST simple. Aquí encontrarás los pasos prácticos para autenticarte, configurar tu cliente y enviar texto para obtener audio sin dependencias externas complejas. El enfoque es directo, priorizando la velocidad de integración y el control de costos por carácter.

La guía cubre desde la obtención de tu clave API hasta la ejecución de la primera petición con cURL o el SDK de OpenAI. Detallamos los parámetros disponibles, los formatos de audio soportados y los límites de uso, como las 60 peticiones por minuto. Todo el código está listo para copiar y pegar, asegurando que puedas generar audio sintético en tu app.

Documentación técnica de la API de texto a voz

Preguntas frecuentes

¿Qué es la base_url en la API?

La base_url es el punto de entrada para las llamadas HTTP. Utiliza https://api.playak444.com/v1 como prefijo. Los endpoints disponibles son POST /v1/audio/speech para generar audio, GET /v1/voices para listar voces y GET /v1/models para ver los modelos disponibles. Esta estructura permite una integración RESTful estándar y predecible.

¿Se puede usar el SDK oficial de OpenAI?

Sí, la API es compatible con el SDK oficial de OpenAI. Solo necesitas cambiar la base_url a https://api.playak444.com/v1 y proporcionar tu clave de API. Esto permite reutilizar el código existente y las bibliotecas oficiales sin modificaciones mayores en la lógica de tu aplicación.

¿Cuántos caracteres caben en una petición?

Cada petición POST puede contener hasta 4096 caracteres de texto en el campo input. 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.

¿Qué formato de audio es mejor para móviles?

Para aplicaciones móviles, MP3 es una opción equilibrada por su compatibilidad y tamaño de archivo. También puedes usar OPUS o WAV para alta calidad. Los formatos FLAC y PCM están disponibles si necesitas audio sin pérdida o sin comprimir, respectivamente, según tus necesidades de almacenamiento.

¿Cómo se maneja la autenticación?

La autenticación se realiza mediante una cabecera Authorization con un token Bearer. El formato es: Authorization: Bearer tts-tu_clave_aqui. Cada cuenta tiene una clave activa. Si emites una nueva, la anterior deja de funcionar inmediatamente. Puedes gestionar tus claves desde la página de configuración de tu cuenta.

¿Qué pasa si supero los 60 rpm?

El límite es de 60 solicitudes por minuto por clave. Si excedes este límite, las solicitudes adicionales se procesarán en una cola hasta que haya capacidad disponible. Esto puede aumentar la latencia de respuesta, pero no causará fallos inmediatos. Las solicitudes fallidas no consumen saldo.

¿Se puede cambiar la velocidad en tiempo real?

La velocidad se configura en el campo request y varía entre 0.25 y 4.0. Este cambio se aplica durante la generación del audio, no en reproducción. Puedes ajustar la velocidad por cada petición individualmente para adaptar el ritmo de la voz sintetizada a las necesidades específicas de tu contenido.

¿Qué significa el código de error 401?

El código 401 indica que la clave de API proporcionada es inválida o ha sido revocada. Verifica que tu token Bearer sea correcto y esté activo. Si emitiste una nueva clave recientemente, la anterior ya no es válida. Asegúrate de que la clave tenga saldo suficiente para la operación.

¿Cómo se especifica el idioma?

Puedes usar el campo language con un código ISO para forzar un idioma específico. Si no se especifica, el sistema intenta adivinarlo basándose en el texto; el texto en latín por defecto es inglés. Para textos en latín que no sean inglés, debes establecer el campo language explícitamente.

¿Es compatible con Android y iOS?

Sí, la API es compatible con Android e iOS mediante llamadas HTTP estándar. Puedes integrar la generación de voz directamente en tus aplicaciones móviles usando las bibliotecas HTTP nativas o el SDK de OpenAI con la base_url personalizada. No hay SDKs específicos de plataforma.

¿Se pueden enviar textos en mayúsculas?

Sí, puedes enviar textos en mayúsculas, minúsculas o mixtas. El motor de síntesis procesa el texto tal como se envía en el campo input. No hay restricciones de formato de texto, aunque el límite de 4096 caracteres sigue aplicándose. La puntuación y los espacios se incluyen en el conteo.

¿Qué ocurre si falla la red?

Si la red falla durante la solicitud, la petición no se completa y no se cobra. El saldo se mantiene intacto. Si la solicitud llega pero la síntesis falla internamente, el cargo también se devuelve íntegramente. Puedes reintentar la solicitud sin penalización económica en caso de errores de red o servicio.

¿Hay versión beta de la API?

No hay una versión beta separada. La API actual es la versión estable v1. Todos los endpoints y comportamientos descritos en la documentación son los disponibles para producción. No se anuncian versiones preliminares ni se realizan cambios disruptivos sin previo aviso en la estructura de los endpoints principales.

¿Cómo se lista la voz por defecto?

No hay una voz por defecto estricta; debes especificar una en el campo voice. Las opciones son: aria, nova, luna, sage, felix, milo, atlas o orion. Puedes obtener la lista completa y sus detalles mediante la llamada GET /v1/voices. Si omites el campo voice, la API devuelve un error.

Primera solicitud

curl

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

Para comenzar a usar la API de VozFlujo, accede a la ruta /get-api-key/ de playak444.com. El registro es inmediato mediante Google o correo electrónico, proporcionando la credencial única necesaria para autenticar tus peticiones.

Una vez registrado, el panel muestra tu clave API activa, el saldo disponible y ejemplos de código listos para copiar. Esto permite integrar la generación de voz en tu aplicación móvil sin pasos adicionales complejos.

Registro con Google o email

Registro con Google o email

Inicia sesión en la página de obtención de clave. El sistema crea una cuenta independiente para este dominio, garantizando que tus datos y uso estén aislados en VozFlujo.

  • Registro instantáneo con Google o email.

Ubicación de la clave en el panel

Ubicación de la clave en el panel

La sección de configuración muestra tu clave Bearer (formato tts-...) junto con el saldo actual y los caracteres restantes. Esta información es esencial para configurar el encabezado de autorización en tus solicitudes.

Emisión de nueva clave

Puedes generar una nueva clave en cualquier momento desde el panel. Al hacerlo, la clave anterior deja de funcionar inmediatamente, lo que permite revocar el acceso de forma segura si es necesario.

Primera petición con cURL

Ilustración de onda de sonido para: Primera petición con cURL

Envía una petición POST a https://api.playak444.com/v1/audio/speech con un cuerpo JSON que especifica el texto y la voz deseada. El endpoint procesa la entrada y devuelve el archivo de audio generado.

Estructura del cuerpo JSON

El cuerpo de la solicitud debe contener los campos model, input y voice. Asegúrate de que el texto no exceda los 4096 caracteres. Los campos opcionales como response_format o speed permiten ajustar el resultado.

Parámetros model, input y voice

El parámetro input acepta la cadena de texto a sintetizar. Usa model para elegir entre "tts-1" o "tts-1-hd", que comparten el mismo motor. El campo voice requiere uno de los 8 presets disponibles, como aria o nova.

Si el texto no está en inglés, establece el parámetro language con el código ISO para evitar que el sistema adivine incorrectamente el idioma.

Respuesta con archivo de audio

La API responde con el archivo de audio en el formato solicitado (mp3, wav, opus, flac o pcm). El archivo se devuelve directamente en el cuerpo de la respuesta HTTP, listo para ser guardado o reproducido en tu 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 mismo esquema de solicitud que el endpoint de speech de OpenAI, lo que permite reutilizar la lógica de integración existente sin reescribir el cliente completo. Solo es necesario ajustar la URL base del cliente para que apunte a https://api.playak444.com/v1 en lugar del dominio original de OpenAI.

Cambio de base_url

Modifica la propiedad base_url en la configuración del cliente para que apunte a https://api.playak444.com/v1. Esta única variación permite que el SDK envíe las peticiones al endpoint correcto POST /v1/audio/speech manteniendo la estructura de cuerpo JSON estándar.

Reutilización de credenciales

La misma clave API obtenida en tu panel funciona directamente con el SDK. No se requiere una conversión de formato ni un token de acceso adicional; simplemente pasa tu clave tts-... como credencial de autorización estándar.

Configuración de cliente

Inicializa el cliente de OpenAI con la nueva URL base y tu clave. El código de integración sigue siendo idéntico al usado para el servicio de OpenAI, garantizando una transición inmediata para equipos móviles que priorizan la velocidad de despliegue.

Formatos de audio soportados

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

La API devuelve audio en los formatos especificados mediante el parámetro response_format. Cada formato se optimiza para diferentes necesidades de integración en aplicaciones móviles, equilibrando calidad y tamaño de archivo.

MP3 para compresión ligera

Formato ideal para reducir el ancho de banda en dispositivos móviles. Ofrece una buena relación calidad-tamaño para la reproducción estándar.

WAV para alta calidad

Formato sin pérdida que preserva la fidelidad original del audio. Recomendado cuando la integridad del sonido es prioritaria sobre el tamaño del archivo.

OPUS, FLAC y PCM

OPUS ofrece compresión eficiente. FLAC garantiza pérdida cero sin la sobrecarga de WAV. PCM proporciona datos crudos sin codificación para procesamiento inmediato.

Límites de la API

Ilustración de onda de sonido para: Límites de la API

La API impone límites claros para garantizar estabilidad y control de costos. Los equipos deben respetar las cuotas de velocidad y longitud para evitar interrupciones en la generación de audio durante la integración en aplicaciones móviles.

Los límites se aplican por clave de API activa. Si superas la cuota, las peticiones adicionales se procesarán una vez liberada la capacidad, manteniendo la secuencia lógica de tu flujo de trabajo.

60 peticiones por minuto

Cada clave permite un máximo de 60 solicitudes por minuto. Este límite es suficiente para la mayoría de los flujos de integración estándar, pero si tu aplicación genera audio de forma masiva, considera agrupar las peticiones.

10 peticiones sin recarga

Hasta que realices tu primera recarga de saldo, la cuota se reduce a 10 peticiones por minuto. Esto permite probar la integración sin bloqueos inmediatos, pero limita la escalabilidad durante la fase inicial.

Límite de 4096 caracteres por petición

Cada cuerpo de petición acepta hasta 4096 caracteres. Para textos más largos, debes dividir la entrada en fragmentos, generar el audio para cada uno y unirlos posteriormente en tu aplicación.

Límites de la API

Manejo de errores

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

La API devuelve códigos de estado HTTP estándar para indicar el resultado de cada solicitud. Los errores de validación o autenticación se resuelven verificando la clave o el formato del cuerpo JSON.

Códigos de status HTTP

Utilizamos respuestas HTTP comunes para guiar la integración. Un código 200 indica éxito y devuelve el archivo de audio. Los errores 4xx señalan problemas en la solicitud, como una clave inválida o texto mal formateado.

Reembolso en fallos de síntesis

Si la síntesis falla, el cargo se devuelve íntegramente. No se descuenta crédito por las peticiones que no generan audio correctamente, asegurando que solo pagues por trabajo completado.

Retries en colas de carga

Las peticiones se procesan en cola. Si el servicio está saturado, una solicitud puede tardar más en completarse. Implementa lógica de reintento para manejar estos casos.

Campos de la petición

Ilustración de onda de sonido para: Campos de la petición

La API acepta texto plano como entrada directa. Cada petición debe contener el texto a sintetizar, respetando el límite de 4096 caracteres por solicitud. Si el texto excede este valor, debes dividirlo en fragmentos y unir los archivos de audio resultantes.

Modelo tts-1 o tts-1-hd

El campo model determina la calidad del motor de síntesis. Ambas opciones, tts-1 y tts-1-hd, utilizan el mismo motor y tienen el mismo precio ($0.01 por cada 1.000 caracteres). La elección depende exclusivamente de la calidad de audio deseada, no del costo.

Velocidad de 0.25 a 4.0

El parámetro speed permite ajustar la velocidad de lectura entre 0.25 (muy lento) y 4.0 (muy rápido). El valor por defecto es 1.0. Esta opción es útil para adaptar la duración del audio a los requisitos de interfaz de usuario sin alterar la entonación de la voz.

Idioma opcional ISO

El campo language acepta un código ISO opcional. Si no se especifica, el sistema infiere el idioma basándose en el script (el texto latino se asume en inglés por defecto). Para textos en idiomas latinos distintos al inglés, se recomienda establecer este campo explícitamente para garantizar la pronunciación correcta.

Autenticación

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

La API requiere autenticación mediante un token Bearer en cada solicitud. Debes incluir la cabecera Authorization con tu clave única para que el servicio reconozca tu cuenta y registre el consumo de caracteres.

La clave se emite durante el registro y es el único mecanismo de acceso. Mantenerla segura es responsabilidad del desarrollador, ya que cualquier persona con ella puede usar tu saldo.

Cabecera Authorization Bearer

Envía tu clave en la cabecera HTTP: Authorization: Bearer tts-tu_clave_aqui. Sin esta cabecera, las peticiones devolverán un error 401 Unauthorized y no se consumirá saldo.

Asegúrate de que la cabecera esté presente en todas las llamadas a los endpoints /v1/audio/speech y /v1/voices.

  • Cabecera: Authorization
  • Valor: Bearer tts-...
  • Formato: Texto plano

Formato tts-...

Las claves comienzan siempre con el prefijo tts- seguido de caracteres alfanuméricos. Este formato permite identificar rápidamente que se trata de una credencial válida de VozFlujo.

Cada cuenta tiene una sola clave activa. No hay límites de caracteres en la clave, pero sí de seguridad: revoca si sospechas una filtración.

  • Prefijo: tts-
  • Longitud: variable
  • Caracteres: alfanuméricos

Revocación instantánea de claves

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

Este mecanismo es útil si compartes la clave temporalmente con un servicio de terceros o si detectas un uso no autorizado en tu historial.

  • Generar nueva clave
  • Invalidación inmediata
  • Sin tiempo de espera

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Cada sitio opera de forma independiente, manteniendo tus credenciales aisladas del resto de la red.

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

Más en este sitio