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.mp3Python (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 | |
|---|---|
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
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
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
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
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
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
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
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.

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
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
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.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
Fuentes y lecturas adicionales
- Wikipedia
- LibriTTS-R paper (arXiv 2305.18802)
- OpenAI API reference: create speech
- Node.js documentation
- LibriVox public-domain audiobooks
- LibriTTS-R corpus (OpenSLR 141)
- Tether (USDT)
- Python documentation
- MDN: Web Speech API
- Creative Commons Attribution 4.0
- W3C WAI: making audio and video accessible
- openai-node on GitHub
