Documentación técnica para API de texto a voz

Por Equipo editorial de VozCreator · Actualizado 2026-11-18

Esta documentación técnica explica cómo integrar nuestra API de texto a voz en tus flujos de trabajo para TikTok, Reels y Shorts. Aquí encontrarás ejemplos prácticos en cURL y Python, junto con la configuración precisa de parámetros como voces, formatos y velocidad. Todo está diseñado para que agregues audio natural a tus videos sin complicaciones técnicas, manteniendo la calidad que tu audiencia espera.

El guía cubre desde la obtención de tu clave API hasta el manejo de límites de tasa y errores comunes. Aprenderás a optimizar costos generando lotes de audio y a manejar textos largos dividiéndolos correctamente. Si trabajas en una agencia y necesitas una solución clara, sin sorpresas ni integraciones complejas, este es tu punto de partida para automatizar la producción de contenido de voz.

Documentación técnica para API de texto a voz

Preguntas frecuentes

¿Cómo obtengo una clave API?

Regístrate en /get-api-key/ con Google o correo electrónico. La página muestra tu clave, saldo y un ejemplo curl listo para usar. Si usas email, no recibirás crédito de prueba; con Google obtienes $0.50 válidos por 7 días.

¿Qué es la base_url en la integración?

Es https://api.playtk1.com/v1. Configura este valor en tu cliente HTTP o SDK para dirigir las peticiones al endpoint correcto. La estructura de la solicitud es idéntica al endpoint de speech de OpenAI, facilitando la migración de proyectos existentes.

¿Cómo uso el SDK de OpenAI con esta API?

Cambia la propiedad base_url a https://api.playtk1.com/v1 y usa tu clave API. El formato del cuerpo JSON es compatible, permitiendo usar las librerías oficiales de OpenAI sin modificar la lógica de tu código de integración principal.

¿Qué formatos de audio puedo solicitar?

Puedes elegir entre mp3, wav, opus, flac y pcm. Estos formatos cubren la mayoría de necesidades para redes sociales y desarrollo. El formato seleccionado se devuelve directamente en la respuesta de la solicitud POST al endpoint de audio.

¿Cuál es el límite de caracteres por solicitud?

Cada solicitud acepta un máximo de 4096 caracteres en el campo input. Si tu texto excede este límite, debes dividirlo en partes más pequeñas. Cada parte se procesará independientemente y deberás unir los archivos de audio resultantes.

¿Cuántas solicitudes puedo hacer por minuto?

El límite es de 60 solicitudes por minuto por clave API. Antes de tu primera recarga, el límite es de 10 por minuto. Si excedes este límite, recibirás un error 429 hasta que el contador se reinicie.

¿Qué significa el error 400?

Indica que la solicitud contiene datos inválidos, como un formato no soportado, una velocidad fuera de rango (0.25–4.0) o un texto vacío. Revisa la estructura JSON y los valores enviados en el cuerpo de la petición.

¿Qué significa el error 401?

Significa que tu clave API es incorrecta o ha sido revocada. Verifica que el encabezado Authorization contenga el prefijo Bearer seguido de tu clave válida. Si emitiste una nueva clave, la anterior dejó de funcionar inmediatamente.

¿Qué significa el error 429?

Indica que has excedido el límite de 60 solicitudes por minuto. Espera a que el contador se reinicie antes de enviar más peticiones. Este límite es por clave API y se aplica estrictamente para mantener la calidad del servicio.

¿Cómo manejo textos largos?

Divide el texto en fragmentos de máximo 4096 caracteres. Envía cada fragmento en una solicitud separada y une los archivos de audio resultantes. Esto asegura que cada parte se sintetice correctamente sin superar los límites de la API.

¿Puedo generar audio en lotes?

Sí, puedes enviar múltiples solicitudes en paralelo o secuenciales. Las solicitudes se procesan una tras otra bajo carga, por lo que tiempos de espera pueden variar. Cada solicitud cuenta por separado contra tu límite de velocidad y saldo.

¿Cómo optimizo mis costos con la API?

Cobra $0.01 por cada 1000 caracteres. Usa el formato mp3 para reducir el tamaño del archivo. Asegúrate de que las solicitudes sean válidas para evitar desperdiciar caracteres en errores.

¿Dónde encuentro más ejemplos de código?

La página /get-api-key/ muestra un ejemplo curl listo para usar. También puedes consultar la documentación general de la API en /docs/. Usa el SDK de OpenAI con nuestra base_url.

¿Cómo contacto al soporte técnico?

El soporte se realiza exclusivamente por correo electrónico. No ofrecemos chat en vivo ni teléfono. Envía tu consulta a la dirección de contacto disponible en la página /contact/ para recibir asistencia con tu cuenta o facturación.

Primera solicitud

curl

curl https://api.playtk1.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.playtk1.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.playtk1.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 clave API

Ilustración de onda de sonido para: Obtención de clave API

La integración comienza accediendo a /get-api-key/ para registrar tu cuenta mediante Google o correo electrónico. Una vez autenticado, la plataforma asigna una clave API única identificable por el prefijo tts-.

Esta clave es el único requisito de autenticación necesario. Se muestra en el panel junto con tu saldo, créditos de prueba y ejemplos listos para copiar, facilitando la primera conexión sin configuraciones complejas.

Registro en la plataforma

Registro en la plataforma

El registro se realiza en /get-api-key/. Puedes usar tu cuenta de Google o crear un usuario con correo y contraseña. Las cuentas con email no incluyen crédito de prueba inicial.

Generación de clave única

Generación de clave única

Se genera automáticamente al acceder. Es una cadena única con prefijo tts-. Solo hay una clave activa por cuenta.

  • Prefijo: tts-

Gestión de claves

Si necesitas renovar tu clave, puedes generar una nueva en cualquier momento. La clave anterior deja de funcionar inmediatamente al emitir la nueva, garantizando seguridad sin interrupciones.

Primera solicitud con cURL

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

Para probar la API sin código, usa una solicitud cURL directa al endpoint de síntesis. Esto te permite verificar la integración rápidamente antes de implementar la lógica en tu aplicación o script de automatización de contenido para redes sociales.

Ejemplo de código cURL

Envía tu texto y voz preferida con este comando básico. Reemplaza tts-xxxxx con tu clave real y ajusta los parámetros según el idioma y el estilo que necesites para tus videos.

  • curl -X POST https://api.playtk1.com/v1/audio/speech \
  • -H "Authorization: Bearer tts-xxxxx" \
  • -H "Content-Type: application/json" \
  • --data '{"model": "tts-1", "input": "Hola mundo", "voice": "nova", "response_format": "mp3"}'

Parámetros requeridos

Los campos esenciales son model (tts-1 o tts-1-hd), input (texto máximo 4096 caracteres) y voice (uno de los 8 presets disponibles). Puedes añadir response_format (mp3, wav, etc.) y speed (0.25–4.0) para ajustar el tono y la duración.

Respuesta esperada

Si la solicitud es válida, recibirás el archivo de audio directamente en la respuesta. Si falla, el sistema devuelve un código de error y el cargo se devuelve en su totalidad.

Integración con OpenAI SDK

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

Nuestra API sigue la misma estructura de solicitudes que OpenAI, lo que permite reutilizar sus SDKs oficiales sin reescribir lógica compleja. Solo necesitas ajustar la URL base para que apunte a nuestro servicio.

Esto simplifica la integración en tus flujos de trabajo existentes de generación de voz para TikTok y Reels, manteniendo la simplicidad de las librerías que ya conoces.

Configuración de base_url

Para conectar tu aplicación, establece la variable de entorno o el parámetro base_url en https://api.playtk1.com/v1. Esto redirige las solicitudes al endpoint correcto sin cambiar la estructura del cuerpo JSON.

  • Base URL: https://api.playtk1.com/v1
  • Endpoint de speech: /v1/audio/speech
  • Método: POST

Uso de bibliotecas oficiales

Utiliza las bibliotecas oficiales de OpenAI (como openai en Python). La clave API se pasa en el encabezado Authorization: Bearer tts-tu-clave, manteniendo la compatibilidad con el formato estándar.

Ejemplos en Python

Inicia la sesión especificando la URL base. Luego, llama a client.audio.speech.create() pasando el texto, el modelo (tts-1 o tts-1-hd) y el formato deseado. La respuesta devuelve el archivo de audio listo para reproducir o guardar.

  • Instala la librería: pip install openai
  • Configura OPENAI_BASE_URL
  • Autenticación con Bearer token

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 flujos de trabajo de TikTok y Reels. Puedes elegir entre MP3, WAV, OPUS, FLAC y PCM mediante el parámetro response_format en la solicitud JSON.

MP3, WAV, OPUS, FLAC, PCM

MP3 y OPUS son ideales para redes sociales por su equilibrio entre calidad y peso. WAV y FLAC ofrecen audio sin pérdida, útiles para ediciones posteriores. PCM proporciona datos crudos para procesamiento personalizado.

  • MP3: estándar para web y apps.
  • WAV/FLAC: alta fidelidad sin compresión.
  • OPUS: formato eficiente para compresión.
  • PCM: datos brutos sin codificar.

Elección de formato según uso

Para videos verticales rápidos, MP3 o OPUS minimizan el tiempo de carga sin sacrificar claridad vocal. Si necesitas editar el audio en un DAW, utiliza WAV o FLAC para evitar artefactos de compresión.

Calidad de audio vs tamaño

Todas las voces usan el mismo motor; el formato solo afecta el tamaño del archivo y la compresión. No hay pérdida de calidad sintética al elegir MP3 para consumo final en plataformas sociales.

Límites y cuotas

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

Para mantener la calidad del servicio y evitar cuellos de botella, cada clave API tiene un límite estricto de 60 solicitudes por minuto. Este umbral se aplica por cuenta y es suficiente para la mayoría de los flujos de trabajo de agencias que generan contenido para TikTok, Reels y Shorts de manera continua sin saturar el sistema.

60 solicitudes por minuto

El límite estándar es de 60 peticiones por minuto por clave activa. Si tu cuenta es nueva y aún no has realizado un recargo, el límite inicial es más bajo: 10 solicitudes por minuto. Este umbral se eleva automáticamente a 60 tras la primera recarga de saldo.

  • Límite estándar: 60 req/min.
  • Límite inicial (sin recargo): 10 req/min.
  • Aplicado por clave API.

4096 caracteres por solicitud

Cada llamada a la API acepta un máximo de 4096 caracteres en el campo input. Esto incluye espacios y puntuación. Si tu guion es más largo, debes dividirlo en fragmentos y unir los archivos de audio resultantes en tu backend para mantener la coherencia del audio final.

Manejo de límites de tasa

Cuando excedes el límite, recibirás un error HTTP 429. Las solicitudes se procesan en cola, por lo que un pico de tráfico puede ralentizar ligeramente la generación en textos largos. Para flujos intensivos, considera distribuir la carga entre varias claves o implementar reintentos con backoff exponencial.

Límites y cuotas

Códigos de error comunes

Ilustración de onda de sonido para: Códigos de error comunes

En la integración de tu API TTS, es crucial manejar los errores comunes para mantener el flujo de generación de audio sin interrupciones. Cada respuesta indica el estado de tu solicitud con códigos HTTP claros.

Error 400: Parámetros inválidos

Ocurre cuando faltan campos requeridos o el formato del JSON es incorrecto. Verifica que model, input y voice estén presentes y que el texto no exceda los 4096 caracteres.

  • Revisa la estructura del cuerpo de la solicitud.
  • Asegúrate de que el código de idioma sea válido si se especifica.

Error 401: Clave incorrecta

Indica que la clave API proporcionada no es válida o ha caducado. Si emitiste una nueva clave, la anterior deja de funcionar inmediatamente. Verifica que el encabezado Authorization incluya el prefijo Bearer.

  • Confirma que la clave comienza con tts-.
  • Revisa si has generado una nueva clave recientemente.

Error 429: Límite excedido

Se devuelve si superas los 60 solicitudes por minuto. Para cuentas nuevas, el límite es de 10 solicitudes por minuto hasta el primer recargo. Implementa lógica de reintento con retroceso exponencial.

  • Monitorea el uso de tu clave activa.
  • Ajusta la velocidad de tus lotes de generación.

Ejemplos de uso avanzado

Ilustración de onda de sonido para: Ejemplos de uso avanzado

La API está diseñada para integrarse en flujos de trabajo de producción de contenido para TikTok, Reels y Shorts. A continuación se muestran estrategias prácticas para escalar la generación de audio manteniendo la calidad y el control de costos.

Generación de audio en lotes

Para agencias que producen múltiples videos diarios, es eficiente generar lotes de audios en paralelo. Dado que las solicitudes se procesan una tras otra bajo carga, el tiempo de espera puede acumularse. Un script simple que maneje la cola localmente permite no bloquear el flujo de trabajo creativo mientras la API sintetiza los archivos.

  • Usa un bucle en tu backend para enviar solicitudes simultáneas.
  • Gestiona la cola para evitar exceder los 60 requests/minuto.
  • Descarga los archivos MP3 u OPUS directamente tras la respuesta 200.

Manejo de textos largos

Cada solicitud acepta hasta 4096 caracteres. Para guiones de videos más extensos, debes dividir el texto en partes y unir los archivos de audio resultantes. Esto evita cortes abruptos y mantiene la coherencia del narrador. La velocidad de generación es aproximadamente tiempo real (25 caracteres por segundo), por lo que textos muy largos pueden tardar varios segundos en completarse.

Actualización de balances (consultable en /get-api-key/).

  • Divide el guion en bloques de <4096 caracteres.
  • Concatena los archivos de audio generados secuencialmente.
  • Verifica que el idioma se especifique explícitamente para textos en latín no ingleses.

Optimización de costos

El precio es de $10 por 1 millón de caracteres. Los espacios y la puntuación cuentan como caracteres, por lo que una limpieza previa del texto puede reducir ligeramente el consumo. Si una síntesis falla, el cargo se devuelve íntegramente, por lo que reintentos automáticos con lógica de backoff son seguros. No hay costos fijos mensuales ni mínimos de gasto.

Usa el formato OPUS para archivos más ligeros sin pérdida perceptible en redes sociales, o MP3 para máxima compatibilidad.

  • Precia el texto antes de enviarlo para estimar el costo exacto.
  • Reutiliza claves API si no se requieren rotaciones frecuentes.
  • Monitorea el uso en /get-api-key/ para ajustar la producción.

Soporte y recursos adicionales

Ilustración de onda de sonido para: Soporte y recursos adicionales

Esta documentación técnica cubre los aspectos esenciales para integrar nuestra API de texto a voz en tus flujos de trabajo de contenido para TikTok, Reels y Shorts. Aquí encontrarás la información necesaria para comenzar a generar audio de alta calidad de manera eficiente.

Para consultas específicas sobre tu integración o dudas técnicas, el soporte es por correo electrónico. No ofrecemos soporte por teléfono ni chat en vivo, pero respondemos a todos los correos lo antes posible para que puedas seguir creando sin interrupciones.

Documentación completa

Puedes explorar todos los detalles técnicos, incluyendo la estructura de los endpoints y los parámetros de la API, en la sección de documentación completa de la plataforma. Allí encontrarás referencias detalladas sobre los modelos tts-1 y tts-1-hd, así como las especificaciones de las voces disponibles.

Ejemplos de código

Además de los ejemplos básicos, puedes consultar integraciones listas para usar en Python y otros lenguajes comunes. Estos recursos te ayudan a entender cómo gestionar las solicitudes, manejar los límites de tasa y optimizar el uso de tu crédito para la generación masiva de voz.

Contacto por correo

Si tienes preguntas sobre tu facturación, el estado de tu cuenta o necesitas aclaraciones técnicas que no encuentres en esta guía, envíanos un correo electrónico. Nuestro equipo de soporte te atenderá directamente para resolver tus dudas sin necesidad de esperas en colas telefónicas.

  • Soporte exclusivo por correo electrónico
  • Sin chat en vivo ni teléfono

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. El saldo no expira, lo que permite acumular crédito para proyectos a largo plazo sin presión de tiempo.

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. curl documentation
  3. openai-node on GitHub
  4. LibriTTS-R corpus (OpenSLR 141)
  5. W3C WAI: making audio and video accessible
  6. Tether (USDT)
  7. openai-python on GitHub
  8. Creative Commons Attribution 4.0
  9. FFmpeg documentation
  10. TRON developer hub: TRC-20
  11. OpenAI API reference: create speech
  12. Python documentation

Más en este sitio