Preguntas frecuentes
¿Qué es la API de texto a voz?
Es un servicio en la nube donde envías texto y recibes un archivo de audio. Solo necesitas enviar una petición POST con el texto y la voz deseada. El endpoint principal es /v1/audio/speech. Es ideal para integrar generación de voz en tus aplicaciones sin necesidad de infraestructura compleja ni servidores propios.
¿Cómo obtengo mi clave API?
Regístrate en /get-api-key/ usando Google o correo electrónico. Una vez creado el cuenta, la página mostrará tu clave API activa. Puedes emitir una nueva clave en cualquier momento; la anterior dejará de funcionar inmediatamente. Esta clave se usa en el encabezado Authorization para autenticar tus peticiones.
¿Qué formato de respuesta devuelve la API?
La API devuelve el archivo de audio directamente en el cuerpo de la respuesta. Puedes elegir entre mp3, wav, opus, flac o pcm mediante el campo response_format. El audio se genera sintéticamente y contiene una marca de agua inaudible que lo identifica como voz artificial.
¿Puedo usar la API con Python?
Sí, puedes usar el SDK oficial de OpenAI cambiando la base_url a https://api.playz18.com/v1. También puedes hacer peticiones HTTP estándar. Solo necesitas configurar tu clave API en el encabezado Authorization. Esto permite integrar la generación de voz fácilmente en scripts o aplicaciones Python existentes.
¿Qué significa el campo 'voice' en la petición?
Define la voz sintética que leerá tu texto. Hay 8 opciones: aria, nova, luna, sage, felix, milo, atlas y orion. Cada una tiene un tono distinto, como narrador cálido o voz enérgica. Debes especificar una de estas voces en cada petición para determinar el estilo de la voz sintetizada.
¿Cuántas peticiones puedo hacer por minuto?
El límite es de 60 peticiones por minuto por clave. Antes de tu primera recarga, el límite es de 10 por minuto. Si excedes el límite, las peticiones podrían tardar más o fallar. Este límite se aplica a todas las solicitudes enviadas con tu clave API activa.
¿Qué pasa si excedo el límite de caracteres?
Cada petición acepta hasta 4096 caracteres. Si tu texto es más largo, debes dividirlo en partes de ese tamaño y unir los archivos de audio resultantes. Los espacios y puntuación cuentan como caracteres. El límite es estricto por petición, no por archivo final.
¿Se pueden combinar voces en un solo audio?
No, la API genera audio con una sola voz por petición. No hay campo para mezclar voces ni para transiciones automáticas entre ellas. Si necesitas diferentes voces, debes generar archivos por separado y unirlos manualmente en tu aplicación o editor de audio.
¿Cómo se maneja el idioma en la API?
Puedes especificar el código ISO del idioma o dejarlo vacío para que se infiera. Si no se especifica, el texto en latín se asume como inglés. Para otros idiomas en latín, es recomendable establecer el campo language explícitamente para evitar errores de pronunciación.
¿Qué formato de audio es mejor para audiolibros?
MP3 es ideal por su equilibrio entre calidad y tamaño. WAV ofrece calidad sin pérdida pero archivos más grandes. FLAC es un formato de audio sin pérdida. Para audiolibros, MP3 suele ser suficiente y eficiente. Elige según tu necesidad de calidad versus espacio de almacenamiento.
Primera solicitud
curl
curl https://api.playz18.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.playz18.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.playz18.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
Accede a la página /get-api-key/ de playz18.com para registrarte con tu cuenta de Google o con correo y contraseña. Una vez dentro, verás tu clave API activa junto con el saldo disponible y el historial de uso.
Registro en la página de claves
El registro es inmediato y genera una cuenta específica para este sitio. Si usas Google, recibirás un crédito de prueba de $0.50 válido por 7 días; con email y contraseña, el saldo comienza en cero.
Copiar tu clave de acceso
La interfaz muestra tu clave activa con el prefijo tts-. Puedes copiarla directamente para usarla en tus scripts o aplicaciones de autoedición.
Seguridad de la clave Bearer
Envía la clave en el encabezado Authorization: Bearer <tu-clave>. Si la expusas o la comprometes, emite una nueva desde el panel; la anterior dejará de funcionar inmediatamente.
- Una clave activa por cuenta
- Reemisión instantánea
- Cabezal estándar Bearer
Primer request con cURL
La API funciona enviando texto plano y recibiendo un archivo de audio. Cada solicitud genera un archivo único mediante un endpoint POST, manteniendo la misma estructura que las herramientas estándar del mercado para facilitar la integración.
El cuerpo de la petición se envía en formato JSON, especificando el modelo, el texto a convertir, la voz elegida y el formato deseado. Este enfoque simple permite convertir manuscritos sin complicaciones técnicas adicionales.
Estructura del JSON de petición
El cuerpo de la solicitud debe contener campos clave que definen la síntesis. Se utiliza un formato JSON estándar que incluye el modelo de IA, el texto fuente (input), la voz que lo interpretará y el formato de salida.
Los parámetros son estrictos: el texto no puede exceder los 4096 caracteres por petición. Si tu manuscrito es más largo, deberás dividirlo en fragmentos y unir los audios resultantes posteriormente.
Parámetros obligatorios y opcionales
Los campos obligatorios son model ("tts-1" o "tts-1-hd"), input (el texto a convertir) y voice (una de las 8 voces disponibles como 'aria' o 'atlas').
Los parámetros opcionales incluyen response_format (mp3, wav, opus, flac, pcm) para elegir la calidad, speed (entre 0.25 y 4.0) para ajustar la velocidad de narración, y language (código ISO) para forzar un idioma específico si la detección automática falla.
- model: "tts-1" o "tts-1-hd"
- input: texto (máx. 4096 caracteres)
- voice: nombre de la voz (ej. "nova")
- response_format: mp3, wav, opus, flac, pcm
- speed: 0.25 a 4.0
- language: código ISO (opcional)
Ejemplo completo de cURL
Puedes probar la API directamente desde la terminal usando cURL. Asegúrate de reemplazar YOUR_API_KEY con tu clave real y de incluir la cabecera Authorization.
Este ejemplo envía un texto breve en formato MP3 utilizando la voz 'luna' con velocidad normal. La respuesta contendrá el archivo de audio listo para ser descargado o reproducido.
Uso con el SDK de OpenAI
La API sigue el mismo formato de petición que el endpoint de speech de OpenAI, lo que permite reutilizar las librerías oficiales sin grandes modificaciones. Solo necesitas ajustar la URL base para que apunte a nuestro servicio.
Modificación del base_url
Para conectar tu aplicación, simplemente cambia la propiedad base_url del cliente de la librería oficial. Debes configurarla para que apunte a https://api.playz18.com/v1. Este cambio permite que las llamadas a la API funcionen exactamente como lo harían con el servicio de referencia, manteniendo la misma estructura de datos.
Compatibilidad con la librería oficial
Al utilizar la misma forma de petición, puedes aprovechar el SDK oficial de OpenAI tanto en Python como en Node.js. No necesitas aprender una sintaxis nueva; solo necesitas proporcionar tu clave API válida en la cabecera de autorización. Esto facilita la integración rápida para proyectos existentes.
Ejemplo en Python y Node.js
En Python, importa OpenAI y define el base_url. En Node.js, la configuración es similar, ajustando la URL base en la instancia del cliente. Ambos ejemplos utilizan la misma estructura JSON para enviar el texto, la voz y el formato deseado, garantizando una experiencia de desarrollo consistente.
Configuración de voces y modelos
Elige entre ocho voces predefinidas que cubren registros masculinos y femeninos, desde narradores claros hasta locutores enérgicos. Cada voz está diseñada para adaptarse a diferentes géneros de autoedición, permitiendo dar vida a tus manuscritos sin necesidad de ajustes técnicos complejos.
Lista de voces disponibles
Disponemos de ocho presets basados en grabaciones con licencia: Aria (narradora), Nova (alegre), Luna (suave), Sage (instructiva), Felix (enérgico), Milo (conversacional), Atlas (neutral) y Orion (profundo). Todas pueden hablar los 23 idiomas soportados, incluyendo español, inglés y alemán.
- Aria: Narradora clara y cálida
- Nova: Tono brillante y animado
- Luna: Suave, ideal para historias
- Sage: Calma, para instrucciones
- Felix: Enérgico, para promociones
- Milo: Amigable y conversacional
Modelos tts-1 y tts-1-hd
El campo model acepta "tts-1" o "tts-1-hd". Ambos utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio.
Endpoint para listar voces
Para obtener la lista exacta de voces, idiomas y formatos disponibles en tiempo real, utiliza el endpoint GET /v1/voices. Esto te permite integrar dinámicamente la selección de voz en tu flujo de trabajo de publicación sin necesidad de hardcodear los nombres.
Formatos de audio soportados
La API de VozIndependiente te permite elegir el formato de salida según tus necesidades específicas, desde la compatibilidad universal hasta la máxima fidelidad. Simplemente especifica el campo response_format en tu solicitud JSON (mp3, wav, opus, flac o pcm) y recibirás el archivo de audio generado al instante.
MP3 para web y móviles
El formato MP3 es ideal para la mayoría de los casos de uso, ofreciendo un equilibrio óptimo entre calidad de audio y tamaño de archivo. Es perfecto para incrustar en páginas web, aplicaciones móviles o plataformas de autoedición donde la velocidad de carga y la compatibilidad con reproductores estándar son prioritarias.
WAV y FLAC para alta calidad
Si necesitas preservar la integridad completa de la voz sintetizada sin pérdidas de compresión, elige WAV o FLAC. Estos formatos son ideales para proyectos de audio profesional, archivar manuscritos en alta definición o cuando necesitas editar el audio generado posteriormente sin degradación notable.
OPUS y PCM para uso técnico
Para casos de uso técnicos o de bajo nivel, OPUS y PCM son formatos de audio disponibles para diferentes necesidades de compresión y datos crudos. Estos formatos son útiles si estás integrando la API en pipelines de procesamiento de audio personalizados o sistemas que requieren datos crudos.

Límites y rendimiento
La API está diseñada para ser predecible y justa. Cada clave de acceso permite hasta 60 peticiones por minuto, lo que facilita la integración en flujos de trabajo de autoedición sin necesidad de sistemas complejos de colas.
Límite de 60 peticiones por minuto
Este límite asegura la estabilidad del servicio. Antes de tu primera recarga, el límite es de 10 peticiones por minuto para pruebas. Una vez agregues saldo mediante USDT (TRC-20), se activa el límite estándar de 60 peticiones por minuto.
Procesamiento secuencial bajo carga
Las solicitudes se procesan una tras otra. Esto significa que, en momentos de alta demanda, una petición podría esperar en cola. La generación de audio es aproximadamente en tiempo real (unos 25 caracteres por segundo de audio generado).
Longitud máxima de 4096 caracteres
Cada petición soporta hasta 4096 caracteres. Para manuscritos más largos, debes dividir el texto en partes y unir los archivos de audio resultantes. Esto te da control total sobre la generación y evita errores por exceso de longitud.
Manejo de errores comunes
La API devuelve códigos HTTP estándar para indicar el estado de cada solicitud. Un 200 confirma que el audio se generó correctamente, mientras que un 401 indica que la clave Bearer es inválida o falta. Si el texto excede los 4096 caracteres, la API devolverá un error.
Errores de autenticación
Si tu clave está mal escrita o expiró tras emitir una nueva, recibirás un 401. Asegúrate de incluir el encabezado Authorization: Bearer tts-... en cada petición.
Límites de velocidad excedidos
El límite es de 60 peticiones por minuto por clave. Si superas este umbral, la API devolverá un 429. Los usuarios nuevos tienen un límite inicial de 10 peticiones por minuto hasta realizar el primer recargo.
Códigos de estado HTTP relevantes
Utiliza estos códigos para automatizar tu flujo de trabajo: 200 (éxito), 400 (error de formato o texto), 401 (autenticación), 404 (recurso no encontrado) y 429 (límite excedido). Un 500 indica un fallo interno temporal.
Codificación de texto e idioma
La API permite enviar texto en múltiples idiomas, pero la precisión depende de configurar correctamente el campo language. Si no se especifica, el sistema intenta deducirlo por el script, asumiendo inglés para textos en latín.
Es crucial establecer el código ISO cuando el texto no es inglés o usa caracteres especiales, evitando errores de pronunciación en acentos y diacríticos que la detección automática podría interpretar incorrectamente.
Uso del campo language
El parámetro language es opcional pero recomendado para textos en idiomas distintos al inglés que usen alfabeto latino. Si no se proporciona, el sistema asume inglés para caracteres latinos, lo que puede afectar la fluidez en español, francés o portugués.
Incluye el código ISO del idioma en tu JSON de solicitud para garantizar que la voz sintetice correctamente la pronunciación nativa, especialmente en mezclas de idiomas o dialectos específicos.
- Código ISO 639-1 (ej: "es", "fr", "de")
- Opcional si el texto es claramente inglés
- Recomendado para precisión en otros idiomas latinos
Detección automática por script
El sistema infiere el idioma principal analizando los caracteres utilizados en el texto de entrada. Si no se especifica, el idioma se infiere del script (el texto en latín asume inglés por defecto).
Esta detección es automática y no requiere intervención manual, pero puede fallar si el texto contiene nombres propios o términos técnicos de otro idioma sin el contexto adecuado.
- Latín → Inglés (por defecto)
- Cirílico → Ruso/Polaco
- Árabe → Árabe
- Kanji/Kana → Japonés
Soporte para acentos y diacríticos
La API soporta caracteres Unicode completos, incluyendo acentos, diéresis, eñes y signos de interrogación invertidos. El texto debe enviarse en UTF-8 para evitar errores de codificación.
Los caracteres especiales se procesan como parte del conteo de caracteres (límite de 4096), así que ten en cuenta que un texto con muchos acentos ocupa la misma longitud que uno sin ellos.
- UTF-8 obligatorio
- Acentos y diéresis soportados
- Conteo exacto de caracteres
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
