Integración de la API de texto a voz en minutos

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

Esta documentación explica cómo integrar la API de texto a voz de ClipVoz en tus flujos de trabajo para TikTok, Reels y Shorts. Utiliza endpoints compatibles con el formato de la API de OpenAI, lo que permite generar archivos de audio directamente desde scripts simples o mediante SDKs oficiales sin necesidad de adaptadores complejos.

Aquí encontrarás ejemplos concretos de uso con cURL y códigos de Python/Node, junto con la referencia completa de parámetros, límites técnicos y formatos de salida. El objetivo es que obtengas el audio listo para editar en minutos, manteniendo la simplicidad que requieren los creadores de contenido no técnicos.

Integración de la API de texto a voz en minutos

Preguntas frecuentes

¿Qué es una API REST?

Es un servicio web que envía texto y recibe audio mediante solicitudes HTTP. Utiliza el endpoint POST /v1/audio/speech con un cuerpo JSON, siguiendo el mismo formato que la API de OpenAI. Esto permite una integración simple y estandarizada para convertir guiones en archivos de audio listos para editar.

¿Necesito conocimientos de programación?

No es estrictamente necesario, pero ayuda. Puedes usar herramientas como cURL o Postman para probar la API sin escribir código. Sin embargo, para automatizar la conversión de guiones largos o integrar el audio en flujos de trabajo, el uso de un script básico facilita la gestión de las solicitudes y la recepción de los archivos.

¿Funciona con el SDK de OpenAI?

Sí. La API tiene la misma forma de solicitud que el endpoint de speech de OpenAI. Solo necesitas cambiar la base_url a https://api.m9999.info/v1 y usar tu clave de ClipVoz. Esto permite reutilizar el código existente del SDK oficial de OpenAI sin modificaciones mayores en la lógica de la solicitud.

¿Cuál es el formato de audio recomendado?

El formato mp3 es ideal para la mayoría de los casos debido a su equilibrio entre calidad y tamaño de archivo. También puedes elegir wav, opus, flac o pcm según tus necesidades de edición. El formato afecta el peso del archivo descargado, pero no el precio de la síntesis, que se cobra por caracteres.

¿Qué significa 4096 caracteres?

Es el límite máximo de texto que puedes enviar en una sola solicitud. Si tu guion es más largo, debes dividirlo en partes de hasta 4096 caracteres y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres dentro de este límite, por lo que debes calcular la longitud total.

¿Cómo se maneja la autenticación?

Se utiliza una clave API única por cuenta, iniciada con el prefijo tts-. Debes incluir esta clave en el encabezado Authorization: Bearer <tu-clave> de cada solicitud HTTP. Si emites una nueva clave, la anterior deja de funcionar inmediatamente, garantizando que solo tu credencial activa pueda acceder a los servicios de síntesis de voz.

¿Puedo usar Python o Node.js?

Sí, puedes usar cualquier lenguaje que soporte solicitudes HTTP o el SDK de OpenAI. Solo necesitas configurar la URL base a https://api.m9999.info/v1. Esto permite integraciones rápidas en scripts de Python o Node.js para automatizar la generación de audio desde tus guiones, aprovechando las bibliotecas estándar o los wrappers existentes.

¿Qué pasa si la API está lenta?

Las solicitudes se procesan en orden secuencial, por lo que bajo carga pueden esperar en una cola. La velocidad típica es de unos 25 caracteres por segundo para textos largos. Si la API está lenta, tu solicitud simplemente espera su turno; no se pierden datos y el audio se entregará una vez procesado completamente.

¿Es necesario usar un modelo específico?

No. Puedes elegir entre tts-1 o tts-1-hd, que utilizan el mismo motor y tienen el mismo precio. La diferencia es principalmente de calidad de audio. Ambos modelos aceptan los mismos parámetros de voz, idioma y formato, por lo que la elección depende de tus necesidades de fidelidad sonora sin afectar el costo por carácter.

¿Cómo verifico el estado de mi pago?

El estado de tu saldo y los cargos se muestran en la página /get-api-key/. Allí puedes ver tu balance actual, el crédito de prueba restante y el historial de uso. Los pagos mediante USDT se acreditan automáticamente en minutos, y el saldo no expira. No hay facturas ni cobros de IVA adicionales en la interfaz.

¿Hay documentación en español?

Esta documentación está escrita en español para facilitar su comprensión. Los parámetros técnicos y los nombres de los campos en el cuerpo JSON siguen la nomenclatura estándar de la API.

¿Puedo hacer múltiples solicitudes?

Sí, tienes un límite de 60 solicitudes por minuto por clave API. Antes de la primera recarga, el límite es de 10 solicitudes por minuto. Si excedes el límite, las solicitudes adicionales podrían tardar más o fallar. Para uso intensivo, considera recargar tu saldo para mantener el límite estándar de 60 solicitudes por minuto.

Primera solicitud

curl

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

Obtención de la clave API

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

Accede a tu clave API desde /get-api-key/. Regístrate con Google para recibir $0.50 de crédito válido 7 días, o usa email y contraseña sin prueba inicial.

Registro con Google

Registro con Google

El registro rápido otorga crédito inmediato. Tu cuenta se crea al instante y ya puedes generar audio.

Registro con email

Registro con email

Crea una cuenta con email y contraseña. No incluye crédito de prueba, pero te da control total desde el inicio.

Gestión de claves activas

Tienes una clave activa por cuenta. Emite una nueva cuando quieras; la anterior deja de funcionar inmediatamente.

Revisa el saldo y el historial de uso directamente en el panel de control.

  • Una sola clave activa por cuenta

Primera solicitud con Curl

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

Para generar audio, envía una solicitud POST a https://api.m9999.info/v1/audio/speech con el cuerpo JSON especificado. La API responde con el archivo de audio binario listo para guardar o editar.

Cuerpo JSON requerido

El cuerpo debe incluir model ("tts-1" o "tts-1-hd"), input (texto máximo 4096 caracteres), voice (uno de los 8 presets) y response_format (mp3, wav, opus, flac, pcm). El campo speed es opcional (0.25–4.0).

Cabecera de autorización

Incluye Authorization: Bearer tts-<tu_clave> en los encabezados. Usa la clave generada en /get-api-key/ para autenticar la solicitud.

Respuesta de audio binario

La respuesta contiene el archivo de audio directo en el cuerpo. Si la síntesis falla, la carga se devuelve íntegramente sin cargo.

Uso con SDK de OpenAI

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

La API es compatible con los SDKs oficiales de OpenAI. Solo necesitas ajustar la variable base_url al endpoint de ClipVoz: https://api.m9999.info/v1. El resto de la lógica de cliente permanece idéntica a la implementación estándar.

Cambio de base_url

Configura el cliente apuntando a la URL base de la API. Esto permite reutilizar la misma librería que usas para otros servicios, cambiando únicamente la dirección del servidor para autenticación y generación de audio.

  • Base URL: https://api.m9999.info/v1
  • Autenticación: Header Authorization: Bearer <tu-clave>

Mismos parámetros

Utiliza exactamente los mismos campos de entrada que el endpoint de OpenAI: model, input, voice y response_format. No se requiere mapeo adicional de campos, lo que simplifica la integración en pipelines existentes de generación de voz.

Lenguajes Python y Node

La integración es directa tanto en entornos Python como Node.js. El SDK maneja la serialización JSON y la descarga del archivo de audio binario resultante sin necesidad de librerías HTTP adicionales ni código de low-level.

Parámetros de la solicitud

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

La API acepta dos modelos, tts-1 y tts-1-hd, que utilizan exactamente el mismo motor de síntesis y tienen el mismo precio. La única diferencia radica en la calidad de audio final; elige tts-1 para mayor eficiencia o tts-1-hd si necesitas un sonido más nítido.

Modelos tts-1 y tts-1-hd

Envia tts-1 o tts-1-hd en el campo model del JSON. Ambos procesan la entrada con la misma velocidad y lógica de generación de voz.

Voces disponibles

Selecciona una de las 8 voces predefinidas con voice. Cada una tiene un timbre específico: femenino (aria, nova, luna, sage) o masculino (felix, milo, atlas, orion). Todas hablan los 23 idiomas soportados sin necesidad de cambiar de modelo.

  • aria: narradora clara
  • nova: enérgica
  • luna: suave
  • sage: instruccional
  • felix: promocional
  • milo: conversacional
  • atlas: neutral
  • orion: documental

Formatos de respuesta

Especifica el audio con response_format. Para redes sociales (TikTok, Reels) usa mp3. Para edición profesional o masterización, selecciona wav, flac o opus. El formato pcm está disponible si necesitas datos de audio sin comprimir.

  • mp3: estándar para web
  • wav: alta calidad
  • flac: pérdida cero
  • opus: eficiente

Limitaciones técnicas

Ilustración de onda de sonido para: Limitaciones técnicas

Cada llamada a la API acepta un máximo de 4096 caracteres por solicitud. Para textos más extensos, es necesario dividirlos en partes y unir los archivos de audio resultantes.

La velocidad de generación se aproxima al tiempo real, con una tasa de aproximadamente 25 caracteres de texto por segundo de audio generado. En cargas altas, las peticiones pueden esperar en cola.

4096 caracteres por request

El campo input acepta hasta 4096 caracteres. Si tu guion excede este límite, debes segmentarlo en múltiples solicitudes y concatenar los archivos de audio devueltos.

Rango de velocidad

Puedes ajustar la velocidad entre 0.25 y 4.0. Por defecto, la síntesis ocurre a velocidad normal. Ten en cuenta que los fragmentos cortos tardan unos segundos en generarse.

Límites de frecuencia

El límite estándar es de 60 solicitudes por minuto por clave API. Si usas la prueba gratuita sin recarga, el límite es de 10 solicitudes por minuto.

Limitaciones técnicas

Manejo de errores

Ilustración de onda de sonido para: Manejo de errores

La API devuelve códigos HTTP estandarizados para indicar el estado de cada solicitud de síntesis. Un código 200 confirma que el audio se generó correctamente, mientras que otros códigos (4xx, 5xx) indican errores específicos que debes manejar en tu integración.

Las solicitudes fallidas no consumen crédito. Si la síntesis falla, el cargo se devuelve íntegramente, lo que permite probar sin riesgo financiero adicional en caso de errores de conexión o formato.

Códigos de estado HTTP

Utiliza los códigos de respuesta HTTP estándar para determinar la acción inmediata. Un 200 OK significa que el archivo de audio está listo en el cuerpo de la respuesta. Los códigos 400-499 indican errores de cliente, como un formato JSON inválido o una voz inexistente. Los códigos 500-599 señalan problemas internos del servidor que suelen ser transitorios.

Solicitudes fallidas

Si la generación de audio falla, el saldo de tu cuenta no se deduce. La API devuelve el monto pagado previamente en caso de haberlo adelantado, o simplemente no registra el cargo si se facturó por uso. Esto garantiza que solo pagues por audio entregado con éxito.

Reintentos recomendados

Implementa un reintento exponencial simple para errores 5xx o de red. Dado que las solicitudes se procesan en cola, un breve retraso entre reintentos ayuda a evitar saturación. Para errores 4xx, verifica la carga JSON antes de reintentar, ya que no se resolverán automáticamente.

  • Códigos 200: Éxito, audio disponible.
  • Códigos 400-499: Error de cliente, verificar parámetros.
  • Códigos 500-599: Error del servidor, reintentar con espera.

Formatos de audio soportados

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

La API devuelve el audio en el formato solicitado. Elige MP3 para redes sociales, WAV para alta calidad, o FLAC y OPUS según tu flujo de trabajo de edición.

El campo response_format acepta los valores: mp3, wav, opus y flac. No hay streaming ni WebSocket; el archivo completo se devuelve al completar la síntesis.

MP3 para redes sociales

Formato recomendado para TikTok, Reels y Shorts. Ofrece la mejor relación entre tamaño de archivo y calidad perceptible. Es universalmente compatible con editores de video no lineales y plataformas de publicación.

Usa response_format: mp3 para ahorrar ancho de banda sin sacrificar la claridad de la voz sintetizada para contenido corto.

  • Compatible con la mayoría de reproductores y editores.
  • Tamaño de archivo reducido para carga rápida.

WAV para alta calidad

Formato de audio sin pérdida ideal para proyectos de postproducción profesional. Mantienes la fidelidad original de la voz generada sin compresión adicional.

Selecciona response_format: wav si tu flujo de trabajo exige la máxima integridad de datos antes de aplicar efectos o mezcla.

  • Audio sin pérdida (lossless).
  • Ideal para archivado o masterización.

FLAC y OPUS

FLAC ofrece compresión sin pérdida, reduciendo el tamaño del archivo WAV manteniendo la calidad exacta. OPUS proporciona compresión con pérdida muy eficiente, ideal para almacenamiento a largo plazo.

Elige flac o opus según tus necesidades de almacenamiento o ancho de banda. Ambos son formatos abiertos y bien soportados.

  • FLAC: compresión sin pérdida.
  • OPUS: alta eficiencia de compresión.

Endpoints disponibles

Ilustración de onda de sonido para: Endpoints disponibles

La API expone tres endpoints principales para la gestión completa del ciclo de síntesis. Todos requieren autenticación Bearer y operan bajo la ruta base https://api.m9999.info/v1.

Generación de speech

El endpoint POST /v1/audio/speech recibe texto y devuelve audio binario. Es el núcleo de la integración para convertir guiones en archivos listos para editar.

Listado de voces

GET /v1/voices devuelve metadatos de las 8 voces disponibles, idiomas soportados y formatos, permitiendo validación dinámica antes de enviar el audio.

Listado de modelos

GET /v1/models retorna la configuración actual de los modelos tts-1 y tts-1-hd, asegurando compatibilidad con versiones futuras de la API.

Escucha las 8 voces

Cada muestra a continuación fue generada por esta API a partir de la misma frase. Utiliza aplicaciones móviles o software de escritorio para combinar el audio con tus clips visuales.

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. ISO 639 language codes
  3. openai-node on GitHub
  4. Creative Commons Attribution 4.0
  5. W3C WAI: making audio and video accessible
  6. LibriVox public-domain audiobooks
  7. LibriTTS-R corpus (OpenSLR 141)
  8. OpenAI API reference: create speech
  9. Python documentation
  10. FFmpeg documentation
  11. Tether (USDT)
  12. LibriTTS-R paper (arXiv 2305.18802)

Más en este sitio