Preguntas frecuentes
¿Cómo se autentiica la solicitud?
Envía tu clave API en el encabezado de la solicitud HTTP. Usa el formato Authorization: Bearer tts-... para autenticar cada llamada a la API. Solo necesitas una clave activa por cuenta. Si emites una nueva, la anterior deja de funcionar inmediatamente.
¿Qué modelos están disponibles?
El endpoint acepta dos modelos: 'tts-1' y 'tts-1-hd'. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. Puedes elegir cualquiera de los dos para tus solicitudes de generación de audio sin diferencias de costo.
¿Cuál es la diferencia entre tts-1 y tts-1-hd?
No hay diferencia funcional ni de precio entre 'tts-1' y 'tts-1-hd'. Ambos utilizan exactamente el mismo motor de síntesis de voz y tienen el mismo costo por millón de caracteres. Puedes usar cualquiera de los dos identificadores en tus solicitudes.
¿Se puede usar el SDK de Python?
Sí, puedes usar el SDK oficial de OpenAI para Python. Solo necesitas cambiar la base_url a https://api.playh99.com/v1 y configurar tu clave API. Esto permite integrar la generación de voz directamente en tus scripts o aplicaciones Python existentes.
¿Cómo se maneja el límite de caracteres?
Cada solicitud acepta un máximo de 4096 caracteres en el campo input. Para textos más largos, debes dividirlos en partes de este tamaño y unir los archivos de audio resultantes. Los espacios y puntuación cuentan como caracteres.
¿Qué pasa si el servidor está ocupado?
Las solicitudes se procesan en cola secuencialmente. Bajo carga, tu solicitud puede esperar antes de comenzar la síntesis. Esto puede aumentar el tiempo de respuesta.
¿Se puede especificar un idioma específico?
Sí, puedes incluir el código ISO del idioma en el campo language de la solicitud. Esto es útil cuando el texto está en un idioma latino pero no es inglés, asegurando que la voz lo pronuncie correctamente según las reglas del idioma indicado.
¿Cómo se detecta el idioma automáticamente?
Si no especificas el campo language, el sistema intenta adivinarlo basado en el script del texto. El texto en latino por defecto se asume como inglés. Para otros idiomas en latino, es recomendable establecer explícitamente el campo language para evitar errores.
¿Qué formato de audio es el más pequeño?
Los formatos disponibles son mp3, wav, opus, flac y pcm. La elección depende de tu necesidad de calidad versus ancho de banda.
¿Se puede transmitir audio en tiempo real?
No, la API no ofrece streaming ni WebSocket para audio parcial. La respuesta devuelve el archivo de audio completo una vez finalizada la síntesis. Las solicitudes se procesan una tras otra, por lo que no hay entrega progresiva de datos durante la generación.
¿Hay documentación para desarrolladores móviles?
No existe un SDK móvil oficial ni una extensión de navegador. Puedes usar HTTP básico o el SDK de OpenAI en tu aplicación móvil para hacer las llamadas a la API. La integración es estándar y funciona en cualquier entorno que soporte peticiones HTTP.
¿Qué significa el código de error 429?
El código 429 indica que has excedido el límite de velocidad de 60 solicitudes por minuto por clave API. Si es tu primera vez, el límite es de 10 solicitudes por minuto hasta realizar tu primer recargo. Espera a que el contador se reinicie.
Primera solicitud
curl
curl https://api.playh99.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.playh99.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.playh99.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 |
Puntos finales (Endpoints)
La API de VozParaTodos expone tres puntos finales principales para la integración técnica. El endpoint principal, POST /v1/audio/speech, recibe texto y devuelve archivos de audio sintetizados. Los endpoints GET /v1/voices y GET /v1/models proporcionan metadatos sobre las voces disponibles, los idiomas soportados y la configuración del modelo.
POST /v1/audio/speech
Este es el núcleo de la API. Envías texto en formato JSON y recibes un archivo de audio binario. Soporta hasta 4096 caracteres por solicitud. Para textos más largos, debes dividir el contenido y unir los archivos resultantes.
- Endpoint: POST https://api.playh99.com/v1/audio/speech
- Formato de entrada: JSON con campos 'model', 'input', 'voice', 'response_format' y 'speed'
- Retorno: Archivo de audio binario en el formato solicitado
GET /v1/voices
Devuelve la lista completa de voces disponibles junto con sus atributos. Incluye información sobre los 23 idiomas soportados y los formatos de audio permitidos. Útil para construir interfaces de selección dinámica.
GET /v1/models
Proporciona detalles sobre los modelos de síntesis disponibles (tts-1 y tts-1-hd). Ambos utilizan el mismo motor y tienen el mismo precio.
Autenticación
Para autenticar tus solicitudes a la API de VozParaTodos, debes incluir una cabecera HTTP personalizada en cada petición. Esto garantiza que el servicio identifique tu cuenta y aplique los límites de uso y facturación correctos.
Cabecera Authorization Bearer
Incluye el siguiente encabezado en tus solicitudes POST o GET:
Authorization: Bearer tts-tu_clave_aqui
La API verificará la validez de la clave antes de procesar la síntesis de voz.
Formato de la clave API
Las claves API comienzan siempre con el prefijo "tts-" seguido de caracteres alfanuméricos. Puedes visualizar tu clave activa, junto con el saldo y el uso, en la página /get-api-key/ de este sitio.
Emisión de nuevas claves
Cada cuenta tiene una única clave activa. Puedes emitir una nueva en cualquier momento desde tu panel. Al generar una nueva, la clave anterior deja de funcionar inmediatamente, lo que facilita la gestión de accesos en tus flujos de trabajo de producto.
Parámetros de solicitud
La API acepta dos modelos idénticos en motor y precio: tts-1 y tts-1-hd. Selecciona el que mejor se ajuste a tus necesidades de latencia o calidad de audio sin costo adicional.
Modelo: tts-1 o tts-1-hd
Ambos modelos utilizan el mismo motor de síntesis. Puedes elegir cualquiera de los dos, ya que tienen el mismo motor y precio. El precio es idéntico para ambos.
Entrada: texto hasta 4096 caracteres
El campo input acepta cadenas de texto de hasta 4096 caracteres por solicitud. Los espacios y la puntuación cuentan como caracteres. Para textos más largos, divide el contenido en fragmentos y une los archivos resultantes.
La velocidad de generación es aproximadamente real-time (25 caracteres por segundo). Bajo carga, las solicitudes pueden esperar en una cola.
Voz: selección de las 8 presets
Elige entre ocho voces predefinidas optimizadas para narración clara y accesible. Cada voz puede hablar cualquier idioma de los 23 soportados.
Las opciones incluyen voces femeninas como aria (narradora cálida) o nova (alegre), y masculinas como milo (conversacional) o atlas (neutral).
Si el idioma no se especifica, el sistema intenta adivinarlo. Para textos en latín que no sean inglés, establece el campo language explícitamente.
- aria: narradora cálida y clara
- nova: brillante y enérgica
- luna: suave, ideal para historias
- sage: calmada, instruccional
- felix: enérgica, promocional
- milo: amigable y conversacional
- atlas: neutral, estilo noticias
- orion: profunda, documental
Formatos de respuesta
La API devuelve el audio generado como un archivo binario directo en el cuerpo de la respuesta. No hay metadatos JSON envolventes, lo que simplifica la escritura del archivo en tu servidor o su reproducción inmediata en el cliente.
MP3, WAV, Opus, FLAC, PCM
Puedes solicitar el formato de salida mediante el campo response_format. Las opciones disponibles son mp3, wav, opus, flac y pcm. Elige según tus necesidades de compatibilidad y calidad sin compromisos adicionales.
- mp3: compatible universalmente, tamaño reducido
- wav: sin pérdida, estándar en edición
- opus: alta eficiencia
- flac: compresión sin pérdida
- pcm: audio crudo sin comprimir
Archivo de audio binario
La respuesta contiene exclusivamente los bytes del archivo de audio. Esto permite integrar la narración generada directamente en tus plataformas digitales sin pasos de conversión adicionales, ideal para servicios públicos y materiales de aprendizaje.
Códigos de estado HTTP
Una respuesta 200 indica éxito y contiene el audio. Si ocurre un error de validación o de límite, recibirás un código 4xx o 5xx con detalles en formato JSON para depurar rápidamente la integración.
Límites y rendimiento
La API está diseñada para integrar narración automática en plataformas digitales sin infraestructura compleja, pero requiere gestión consciente de la concurrencia. Cada clave API tiene un límite estricto de 60 solicitudes por minuto, lo que permite a los equipos de producto en servicios públicos y ONGs generar audio de forma predecible. Si superas este umbral, las solicitudes adicionales se procesarán una vez que haya capacidad disponible.
60 solicitudes por minuto
El límite de tasa se aplica por clave API activa. Para cuentas nuevas, el límite inicial es de 10 solicitudes por minuto hasta la primera recarga de saldo. Una vez que se realiza la primera recarga, el límite aumenta a 60 solicitudes por minuto, permitiendo una generación de audio más fluida para tus flujos de trabajo multilingües.
- Límite estándar: 60 solicitudes/minuto por clave.
- Límite inicial: 10 solicitudes/minuto antes de la primera recarga.
Cola de procesamiento bajo carga
Las solicitudes se procesan en orden de llegada. Si la API está experimentando alta demanda, tu solicitud puede esperar en una cola antes de comenzar la síntesis. Esto es normal y no indica un fallo; simplemente significa que el motor está optimizando recursos para mantener la estabilidad del servicio.
Velocidad de generación aproximada
La generación de audio es aproximadamente en tiempo real para textos largos, procesando unos 25 caracteres por segundo de audio generado. Para frases cortas, la generación puede tomar unos pocos segundos adicionales debido a la sobrecarga inicial. Para textos extensos, se recomienda dividir el texto en partes de hasta 4096 caracteres para optimizar la eficiencia.

Uso con SDK de OpenAI
La API de VozParaTodos es compatible con las librerías oficiales de OpenAI. Solo necesitas cambiar la URL base a https://api.playh99.com/v1. Esto permite usar los mismos métodos de generación de audio que conoces, manteniendo la estructura de peticiones idéntica.
Cambio de base_url
Configura el cliente apuntando a la dirección de la API. Este ajuste permite que las llamadas estándar funcionen sin modificar la lógica de tu aplicación.
Compatibilidad con librerías oficiales
Las SDKs oficiales de OpenAI funcionan directamente. No se requiere una biblioteca propia ni adaptadores complejos para integrar la generación de voz.
Configuración de clave API
Envía tu clave única en la cabecera Authorization: Bearer. Esta credencial se genera en tu panel de cuenta y autoriza cada solicitud.
Manejo de errores
La API devuelve errores específicos cuando los parámetros no cumplen los requisitos, como exceder los 4096 caracteres o usar una voz inválida. Estas respuestas permiten corregir la solicitud.
En caso de fallos de síntesis, la carga se devuelve íntegramente, garantizando que solo se pague por audio generado con éxito.
Errores de validación
La API valida el formato JSON y los rangos permitidos antes de iniciar el procesamiento. Si el texto excede el límite de caracteres o el formato no es compatible, se recibe un error 400 con una descripción clara del problema.
- Textos > 4096 caracteres
- Voz no existente en la lista
- Formato de audio no soportado
Excepciones de límite
Se aplica un límite de 60 solicitudes por minuto por clave. Si se excede, la API devuelve un error 429. Antes de la primera recarga, el límite es de 10 solicitudes por minuto.
- Error 429 Too Many Requests
- Espera necesaria antes del siguiente intento
Reintento de solicitudes fallidas
Las solicitudes que fallan durante la generación no se cobran. Implementa lógica de reintento con backoff exponencial para manejar interrupciones temporales en la cola de procesamiento bajo carga.
Ejemplo de solicitud cURL
Este ejemplo demuestra la integración directa con la API. Utiliza un texto corto en español y la voz "aria", ideal para narraciones claras en servicios públicos.
Comando básico de POST
Envía una solicitud POST al endpoint de síntesis. El cuerpo JSON incluye el modelo "tts-1" y el texto a convertir.
Inclusión de cabecera de autorización
La cabecera Authorization: Bearer tts-tu-clave autentica la solicitud. Usa la clave generada en tu panel de control.
Especificación de formato de salida
Define response_format como "mp3" para compatibilidad universal. Otros formatos como "wav" o "opus" están disponibles según necesidades de calidad.
- Modelo: tts-1
- Voz: aria
- Idioma: es (opcional)
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Este enfoque elimina la necesidad de aprender protocolos propietarios, permitiendo a los equipos de producto centrarse en la lógica de negocio.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
