Documentación de la API de texto a voz para autoedición

Por equipo editorial de VozIndependiente · Actualizado 2026-11-18

Esta guía técnica explica cómo integrar nuestra API de texto a voz en tus flujos de trabajo de autoedición. Aprenderás a autenticarte, enviar texto y recibir archivos de audio mediante cURL o el SDK de OpenAI, sin necesidad de conocimientos avanzados.

Está pensada para autores independientes y desarrolladores que buscan automatizar la conversión de manuscritos. Encontrarás ejemplos concretos de parámetros, límites de uso y gestión de errores para que puedas generar audiobooks de calidad con precisión y control total.

Documentación de la API de texto a voz para autoedición

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.mp3

Python (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
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

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

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

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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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.

Formatos de audio soportados

Límites y rendimiento

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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

Ilustración de onda de sonido para: 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.

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-python on GitHub
  3. Python documentation
  4. W3C WAI: making audio and video accessible
  5. LibriVox public-domain audiobooks
  6. curl documentation
  7. Creative Commons Attribution 4.0
  8. MDN: Web Speech API
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. openai-node on GitHub
  11. Node.js documentation
  12. ISO 639 language codes

Más en este sitio