Documentación completa de la API de texto a voz

Por equipo editorial de SonidoNet · Actualizado 2026-11-19

Esta documentación está diseñada para desarrolladores indie que necesitan integrar voz natural en asistentes o chatbots con mínima complejidad. Aquí encontrarás ejemplos concretos, desde solicitudes curl hasta integración con el SDK de OpenAI, para que empieces a generar audio en minutos.

Cubre todos los aspectos técnicos esenciales: autenticación con clave Bearer, parámetros como modelo, voz y velocidad, y el manejo de textos largos divididos en partes. No hay sorpresas ni funciones ocultas, solo la API de texto a voz que necesitas para tu aplicación, explicada paso a paso.

Documentación completa de la API de texto a voz

Preguntas frecuentes

¿Qué SDK puedo usar?

Puedes usar las SDK oficiales de OpenAI cambiando el base_url a https://api.pak500.info/v1 y usando tu clave de API. No tenemos una SDK propia ni móvil, así que la integración se realiza mediante llamadas HTTP directas o las librerías de OpenAI.

¿Es compatible con la librería de OpenAI?

Sí, el endpoint y el formato de solicitud son idénticos al de OpenAI. Solo necesitas ajustar la URL base a https://api.pak500.info/v1 y usar tu clave tts-.... Esto permite reutilizar código existente de OpenAI sin modificar la lógica de la solicitud, facilitando la integración rápida en tus proyectos de desarrollo.

¿Cómo cambio la velocidad de la voz?

Incluye el campo speed en el cuerpo JSON de tu solicitud, con un valor entre 0.25 y 4.0. El valor predeterminado es 1.0. Esto te permite acelerar o ralentizar la generación de audio según las necesidades de tu aplicación, manteniendo la naturalidad de la voz sintética generada por la API.

¿Qué idiomas puedo especificar?

Puedes especificar hasta 23 idiomas, como inglés, español, alemán, japonés o chino. Si no indicas el código ISO, el sistema intenta adivinarlo (el texto latino por defecto es inglés). Para textos en latinos no ingleses, establece explícitamente el campo language para evitar que se asuma inglés.

¿Qué formato devuelve la API?

La API devuelve audio en los formatos mp3, wav, opus, flac o pcm. Especifica el formato deseado en el campo response_format de tu solicitud JSON. Estos formatos cubren la mayoría de las necesidades de reproducción en aplicaciones web y móviles, permitiendo elegir entre compresión o calidad sin pérdida según tu infraestructura.

¿Cómo se autentica la solicitud?

Incluye tu clave API en el encabezado de la solicitud HTTP: Authorization: Bearer tts-.... Cada cuenta tiene una clave activa que puedes renovar en cualquier momento; al emitir una nueva, la anterior deja de funcionar inmediatamente. Esta autenticación simple asegura que solo tú puedas usar tu saldo y generar audio.

¿Qué pasa si excedo los límites?

El límite es de 60 solicitudes por minuto por clave (10 antes del primer recargo). Si excedes este límite, las solicitudes adicionales podrían tardar más o fallar. Los pedidos se procesan en cola, por lo que bajo carga alta puedes experimentar retrasos. Monitorea tu uso en el panel para evitar interrupciones en tu aplicación.

¿Cómo se manejan los errores?

Si la síntesis falla, la carga se devuelve completamente y no se descuenta de tu saldo. Recibirás una respuesta de error con detalles para que puedas depurar tu solicitud. Esto garantiza que solo pagues por el audio generado con éxito, protegiendo tu presupuesto incluso si ocurren problemas técnicos durante el procesamiento de la voz.

¿Es necesario instalar algo?

No, no necesitas instalar nada específico. Solo necesitas capacidad de red para enviar solicitudes HTTP a la API. Puedes usar cualquier lenguaje de programación que soporte peticiones HTTP, como Python, JavaScript o Go. La integración es puramente basada en la nube, sin dependencias locales complejas ni SDKs nativos adicionales (como las de OpenAI).

¿Puedo usar la API desde Node.js?

Sí, funciona perfectamente con Node.js. Puedes usar la SDK de OpenAI configurando la URL base o enviar solicitudes fetch estándar. Simplemente importa la librería, configura el cliente con tu clave y endpoint, y envía el texto. Es ideal para aplicaciones web serverless o backend Node.js que necesitan generar audio dinámicamente.

¿Cómo se generan las claves?

Las claves se generan al crear una cuenta en la página /get-api-key/. Puedes registrarte con Google o correo electrónico. La clave se muestra en tu panel de control y puedes emitir una nueva en cualquier momento; la anterior deja de funcionar inmediatamente. Esto te permite rotar credenciales si es necesario sin perder acceso.

¿Qué es el endpoint /v1/voices?

Este endpoint devuelve información sobre las 8 voces disponibles, los idiomas soportados, los formatos de audio y los precios. Es útil para construir interfaces de usuario dinámicas que permitan a los usuarios seleccionar su voz preferida antes de enviar la solicitud de síntesis.

¿Qué devuelve /v1/models?

Devuelve información sobre los modelos disponibles, específicamente tts-1 y tts-1-hd. Ambos usan el mismo motor y tienen el mismo precio. Este endpoint permite verificar qué modelos están activos y sus características técnicas.

¿Cuánto tarda la respuesta?

El tiempo es aproximadamente en tiempo real para textos largos (25 caracteres por segundo). Las frases cortas pueden tardar unos segundos. Las solicitudes se procesan en cola, por lo que bajo carga alta puede haber retrasos adicionales. La respuesta final contiene el archivo de audio completo listo para reproducir o guardar.

Primera solicitud

curl

curl https://api.pak500.info/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.pak500.info/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.pak500.info/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

Obtén tu clave API

Ilustración de onda de sonido para: Obtén tu clave API

Para integrar voz en tus aplicaciones, primero necesitas una clave de API. El proceso es rápido y se completa en la página /get-api-key/ de pak500.info, donde puedes elegir entre dos métodos de registro sencillos.

Una vez registrado, accedes a un panel donde se muestra tu clave activa, tu saldo y ejemplos de código listos para copiar. Esta clave es el único requisito para empezar a generar audio mediante llamadas HTTP.

Registro con Google

Registro con Google

Inicia sesión con tu cuenta de Google para obtener una clave de inmediato. Este método asigna automáticamente un crédito de prueba de $0.50 (aproximadamente 50 000 caracteres) con validez de 7 días.

Es ideal para probar la API sin necesidad de ingresar datos de pago inmediatamente y verificar que la integración funciona correctamente en tu entorno.

  • Acceso inmediato sin formulario adicional
  • Incluye crédito de prueba de $0.50
  • Válido por 7 días

Registro con email

Registro con email

Crea una cuenta usando un correo electrónico y una contraseña. Este método no incluye el crédito de prueba inicial, por lo que deberás realizar un recargo para comenzar a generar audio.

Es la opción recomendada para proyectos serios o si prefieres separar tu identidad personal de Google de tu cuenta de desarrollador.

  • Control total sobre las credenciales
  • Ideal para equipos o proyectos comerciales
  • Sin crédito de prueba automático

Gestión de claves

Cada cuenta tiene una sola clave activa visible en el panel. Si sospechas que fue comprometida o simplemente quieres renovar tu seguridad, puedes emitir una nueva clave en cualquier momento.

La clave anterior deja de funcionar inmediatamente al generar la nueva, garantizando que solo tengas un punto de acceso activo.

Las solicitudes fallidas no se cobran, lo que facilita el desarrollo y la depuración sin preocuparte por el consumo de saldo durante las pruebas.

  • Una sola clave activa por cuenta
  • Rotación inmediata y segura

Primera solicitud con curl

Ilustración de onda de sonido para: Primera solicitud con curl

Para probar la API, envía una solicitud POST a https://api.pak500.info/v1/audio/speech con tu clave Bearer. El servicio procesa el texto y devuelve el archivo de audio generado directamente en la respuesta.

Este método básico te permite verificar rápidamente la integración sin necesidad de librerías complejas, ideal para iniciar tu primer prototipo de asistente de voz o chatbot.

Comando POST completo

Usa cURL para enviar la solicitud. Reemplaza YOUR_KEY con tu clave real y ajusta los parámetros según tus necesidades de modelo y voz.

El comando debe incluir los encabezados de autenticación y el cuerpo JSON con el texto a sintetizar.

  • curl -X POST https://api.pak500.info/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Hola mundo", "voice": "nova"}'

Cuerpo JSON de ejemplo

El cuerpo de la solicitud requiere al menos los campos model, input y voice. Puedes añadir language para forzar un idioma específico.

El texto de entrada tiene un límite de 4096 caracteres por solicitud. El formato predeterminado es mp3 (si no se especifica response_format).

  • {
  • "model": "tts-1",
  • "input": "Bienvenido a SonidoNet.",
  • "voice": "nova",
  • "response_format": "mp3"
  • }

Respuesta de audio

La API responde con el archivo de audio binario o un error JSON si la solicitud falla. Si la síntesis tiene éxito, el audio se descarga o guarda en tu aplicación.

Si la solicitud falla, no se cobra el crédito y recibes un código de estado HTTP indicando el problema.

Uso con SDK de OpenAI

Ilustración de onda de sonido para: Uso con SDK de OpenAI

Integra SonidoNet en tus apps sin rehacer tu código. Solo cambia la URL base del SDK y reutiliza la lógica de audio que ya conoces.

Las librerías oficiales de OpenAI en Python, Node.js, Go, etc. funcionan perfectamente con nuestra API.

Ajusta base_url a https://api.pak500.info/v1 y pasa tu clave. El resto es idéntico al endpoint de speech de OpenAI.

Cambio de base_url

Modifica la configuración de tu cliente SDK para apuntar a https://api.pak500.info/v1. Esto redirige todas las peticiones a nuestro endpoint sin alterar la estructura del cuerpo JSON.

Asegúrate de que tu clave API comience por tts- y se pase en la cabecera Authorization. La sintaxis de la solicitud permanece idéntica a la de OpenAI.

  • base_url: https://api.pak500.info/v1
  • Cabecera: Authorization: Bearer tts-...

Librerías oficiales

Puedes usar las librerías oficiales de OpenAI en Python, Node.js, Go, etc. No necesitas aprender una API nueva ni instalar paquetes adicionales específicos de SonidoNet.

La compatibilidad es total porque seguimos el mismo formato de solicitud. Solo necesitas configurar correctamente la URL base y las credenciales en tu entorno de desarrollo.

Ejemplo en Python

```python import openai client = openai.OpenAI(base_url="https://api.pak500.info/v1", api_key="tts-tu-clave") with client.audio.speech.create( model="tts-1", voice="nova", input="Hola, esto es una prueba de integración con SonidoNet." ) as response: response.stream_to_file("output.mp3") ``` Este snippet muestra cómo generar y guardar audio con una sola llamada, reutilizando la familiar estructura de la librería de OpenAI para tus asistentes o chatbots.

Parámetros de la solicitud

Ilustración de onda de sonido para: Parámetros de la solicitud

La API acepta dos valores para el campo model: tts-1 y tts-1-hd. Ambos utilizan el mismo motor de síntesis y tienen idéntico precio, por lo que puedes elegir el que prefieras sin impacto en el costo ni en la calidad base del audio generado.

Modelo tts-1 y tts-1-hd

El campo model acepta únicamente los valores tts-1 o tts-1-hd. Ambos utilizan exactamente el mismo motor de síntesis y tienen el mismo precio por carácter. No hay diferencia funcional ni de costo entre ambos; puedes enviar cualquiera de los dos en tu petición sin variaciones en la calidad del audio resultante.

Voz y formato de respuesta

Selecciona una de las 8 voces predefinidas mediante el campo voice. Las opciones incluyen perfiles femeninos como aria o nova, y masculinos como atlas o orion. Para el formato de salida, especifica mp3, wav, opus, flac o pcm mediante response_format, garantizando compatibilidad con tu aplicación.

Si no especificas un formato, la API devuelve mp3 por defecto. Recuerda que cada archivo generado contiene una marca de agua invisible que lo identifica como voz sintética.

  • Aria, Nova, Luna, Sage (femeninas)
  • Felix, Milo, Atlas, Orion (masculinos)
  • Formatos: mp3, wav, opus, flac, pcm

Velocidad y idioma

El campo speed permite ajustar la velocidad de lectura entre 0.25 y 4.0. Un valor de 1.0 representa la velocidad natural. Esto es útil para ajustar la velocidad de tus asistentes de voz o chatbots sin depender de la reproducción del cliente.

El campo language es opcional. Si se omite, el sistema intenta adivinar el idioma basándose en el texto (el texto en latín se asume como inglés por defecto). Para textos en otros idiomas con escritura latina, especifica el código ISO para evitar errores.

  • Rango de velocidad: 0.25 a 4.0
  • Idioma por defecto: Inglés (para texto latino)
  • Códigos ISO opcionales para precisión

Autenticación y seguridad

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

La autenticación se gestiona mediante una clave API única visible en tu panel. Cada solicitud debe incluir esta credencial en la cabecera HTTP para identificar tu cuenta y verificar el saldo disponible.

Cabecera Authorization Bearer

Incluye siempre el encabezado Authorization: Bearer tts-... en tus peticiones. Sin esta cabecera, la API devolverá un error de autenticación y no consumirá tu saldo.

  • Usa el método HTTP POST estándar.
  • Asegúrate de que la cabecera esté en cada llamada.

Formato de la clave tts-...

Tu clave comienza por tts- y se genera al registrarte. Es el único identificador activo para tu cuenta en este momento.

Rotación de claves

Puedes emitir una nueva clave desde el panel en cualquier momento. La clave anterior deja de funcionar inmediatamente, lo que garantiza que solo tú controlas el acceso a tu API.

Autenticación y seguridad

Límites y errores

Ilustración de onda de sonido para: Límites y errores

La API tiene límites claros para garantizar un funcionamiento estable. Conocer estos límites te ayuda a estructurar bien tus llamadas y evitar errores comunes en la integración.

Si superas los límites, recibirás respuestas específicas que indican exactamente qué ajuste necesitas hacer en tu código o en tu flujo de trabajo.

60 solicitudes por minuto

Cada clave API permite un máximo de 60 solicitudes por minuto. Antes de tu primera recarga, este límite se reduce a 10 solicitudes por minuto.

Las solicitudes se procesan en cola, por lo que bajo carga una petición puede tardar más tiempo en completarse.

  • Límite estándar: 60 req/min
  • Límite inicial: 10 req/min
  • Procesamiento secuencial

Límite de 4096 caracteres

Cada solicitud puede contener hasta 4096 caracteres de texto. Los espacios y la puntuación cuentan como caracteres.

Para textos más largos, debes dividirlos en partes y unir los archivos de audio resultantes.

  • Máximo 4096 caracteres por petición
  • Espacios y puntuación incluidos
  • División manual para textos largos

Códigos de estado HTTP

Los errores comunes incluyen 400 (solicitud incorrecta) y 429 (límite de tasa excedido).

Las solicitudes fallidas no generan cargos, por lo que el crédito se devuelve automáticamente.

  • 400: Solicitud incorrecta
  • 429: Límite de tasa excedido
  • 200: Éxito

Manejo de textos largos

Ilustración de onda de sonido para: Manejo de textos largos

La API recibe un máximo de 4096 caracteres por solicitud. Para textos más extensos, debes dividirlos manualmente en fragmentos de ese tamaño antes de enviarlos.

División manual en partes

Calcula la longitud de tu texto y sepáralo en bloques de hasta 4096 caracteres. Cada bloque se envía como una solicitud independiente.

Unión de archivos de audio

Recibirás un archivo de audio por cada solicitud. Concatena estos archivos en el orden original para obtener el audio completo del texto.

Gestión de la cola

Las solicitudes se procesan en orden. Bajo carga, puede haber espera en cola, pero el resultado final mantendrá la secuencia correcta.

Formatos de audio soportados

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

La API ofrece cinco formatos de salida para adaptarse a tus necesidades de infraestructura y calidad. Elige el formato que mejor equilibre el tamaño del archivo con la fidelidad del audio generado para tus asistentes de voz o chatbots.

MP3 para compatibilidad

Es el formato predeterminado y más compatible. Ideal para la mayoría de las integraciones web y móviles donde la eficiencia del almacenamiento no es la prioridad principal, pero la reproducción universal sí.

  • Reproducción universal en navegadores y reproductores móviles
  • Tamaño de archivo moderado
  • Formato predeterminado en la API

WAV para alta fidelidad

Proporciona audio sin pérdida de calidad. Úsalo cuando necesites la máxima precisión sonora para procesamiento posterior o grabaciones profesionales, aceptando el mayor consumo de almacenamiento y ancho de banda.

  • Sin compresión de datos
  • Máxima fidelidad sonora
  • Ideal para procesamiento de señal

Opus y FLAC para eficiencia

Opus ofrece una excelente relación calidad-tamaño para streaming, mientras que FLAC proporciona compresión sin pérdida pero con archivos más pequeños que WAV. Ambos son ideales para optimizar el ancho de banda sin sacrificar la experiencia del usuario.

  • Opus: alta eficiencia para streaming
  • FLAC: compresión sin pérdida
  • Reducción significativa del tamaño

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Coloca lado a lado las voces femeninas y masculinas para comparar calidez frente a neutralidad.

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 corpus (OpenSLR 141)
  3. LibriTTS-R paper (arXiv 2305.18802)
  4. openai-python on GitHub
  5. LibriVox public-domain audiobooks
  6. Python documentation
  7. curl documentation
  8. Node.js documentation
  9. MDN: Web Speech API
  10. IETF RFC 7845: Ogg Opus
  11. Tether (USDT)
  12. ISO 639 language codes

Más en este sitio