Preguntas frecuentes
¿Qué es un endpoint API?
Es la dirección URL donde envías tus solicitudes. Para esta API, el endpoint es POST https://api.chasus33.info/v1/audio/speech. Debes enviar un cuerpo JSON con el texto, el modelo y la voz deseada. La respuesta contendrá el archivo de audio generado o un código de error si la síntesis falla.
¿Cómo cambio la velocidad del audio?
Incluye el campo speed en tu solicitud JSON con un valor entre 0.25 y 4.0. El valor predeterminado es 1.0. Un valor menor ralentiza la narración y uno mayor la acelera. Esto te permite ajustar el ritmo del contenido para adaptarlo mejor al estilo de tus videos de YouTube.
¿Puedo usar el SDK de OpenAI?
Sí, las solicitudes tienen la misma forma que el endpoint de speech de OpenAI. Solo necesitas cambiar la base_url a https://api.chasus33.info/v1 y usar tu clave API de VozNarradora. Esto permite reutilizar el código existente sin necesidad de aprender una sintaxis de solicitud completamente nueva.
¿Qué formato es mejor para YouTube?
MP3 es el formato más eficiente para subir a YouTube debido a su equilibrio entre calidad y tamaño de archivo. También puedes usar WAV para máxima calidad sin compresión, u Opus para una compresión aún mayor. Elige según tus necesidades de almacenamiento y ancho de banda para la publicación de tus videos.
¿Cuántas solicitudes puedo hacer por minuto?
El límite es de 60 solicitudes por minuto por clave API. Si tu cuenta no ha realizado un recargo de saldo, el límite es de 10 solicitudes por minuto. Este control asegura que los recursos del servidor se distribuyan equitativamente entre todos los usuarios activos de la plataforma de generación de voz.
¿Qué pasa si excedo el límite?
Las solicitudes adicionales recibirán un error indicando que has excedido la cuota. Deberás esperar hasta que el contador de tiempo se reinicie para el siguiente minuto. No se te cobrará por las solicitudes que fallen o no se procesen.
¿Cómo rotar mi clave API?
Puedes emitir una nueva clave API en cualquier momento desde tu panel de cuenta. La clave anterior dejará de funcionar inmediatamente al generar la nueva. Esto es útil para seguridad o si sospechas que tu clave ha sido expuesta. La nueva clave tendrá los mismos límites y saldo de tu cuenta.
¿El audio tiene marcas de agua?
Sí, cada archivo de audio generado lleva una marca de agua inaudible que lo identifica como voz sintética. Esta marca es imperceptible para el oyente humano pero permite verificar el origen del audio. Es una característica estándar de nuestro motor de síntesis para garantizar la transparencia del contenido generado por IA.
¿Puedo usar la API en mi servidor?
Absolutamente. La API está diseñada para ser consumida programáticamente desde cualquier servidor capaz de enviar solicitudes HTTP POST. Puedes integrarla en tu pipeline de producción de videos o en la infraestructura de tu agencia para automatizar la generación de narraciones a gran escala sin intervención manual constante.
¿Es compatible con Linux y Windows?
Sí, ya que es una API REST estándar basada en HTTP, funciona en cualquier sistema operativo que soporte solicitudes de red. Puedes usarla desde servidores Linux, estaciones de trabajo Windows o macOS. Solo necesitas poder enviar datos JSON y recibir la respuesta de audio en tu entorno de desarrollo preferido.
¿Cómo se manejan los errores 500?
Si recibes un error 500, la solicitud no se completó correctamente y no se te cobrará. El sistema devuelve un código de estado indicando el fallo. Deberás revisar tus parámetros o intentar la solicitud nuevamente. Los errores de síntesis son gratuitos, asegurando que solo pagues por audio generado con éxito.
¿Puedo especificar el idioma manualmente?
Sí, puedes incluir el campo language con un código ISO en tu solicitud. Si no lo especificas, el sistema intentará adivinar el idioma basado en el script del texto. Para textos en latín que no sean inglés, es recomendable establecer el idioma manualmente para evitar errores de pronunciación en la narración.
¿Qué es el modelo tts-1-hd?
Es uno de los dos modelos disponibles, junto con tts-1. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. La elección entre ellos depende de tus preferencias, aunque técnicamente comparten la misma capacidad base de generación de voz.
¿Necesito conocimientos técnicos?
Se requiere conocimiento básico para enviar solicitudes JSON y manejar respuestas de API. Puedes usar herramientas como cURL o el SDK de OpenAI para simplificar la integración. Si sabes cómo hacer una petición HTTP, puedes integrar la narración en tus flujos de trabajo de producción de video sin necesidad de ser un experto en desarrollo.
Primera solicitud
curl
curl https://api.chasus33.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.chasus33.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.chasus33.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 | |
|---|---|
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 |
Obtención de la clave API
La integración comienza accediendo a /get-api-key/ para crear tu cuenta mediante Google o correo electrónico. Una vez registrado, la interfaz muestra tu clave API activa, el saldo disponible y un ejemplo listo para copiar, eliminando la necesidad de pasos adicionales de configuración.
Esta clave funciona como tu identificador único para todas las solicitudes. Para los creadores de contenido y agencias que necesitan escalar la producción de voz sin fricción técnica, el acceso inmediato a los recursos es el primer requisito para mantener el flujo de trabajo.
Registro en /get-api-key/
Visita la página de registro para iniciar sesión con Google o crear una cuenta con correo y contraseña. El sistema asigna automáticamente una clave Bearer inicial y muestra el estado de tu cuenta, incluyendo el saldo de prueba de $0.50 si la cuenta fue creada con Google.
La interfaz centraliza la información crítica: tu clave API, el balance actual y los caracteres restantes. Esto permite comenzar a probar las solicitudes inmediatamente sin navegar por múltiples menús o configuraciones de cuenta complejas.
Generación de clave Bearer
La autenticación se realiza mediante el encabezado Authorization: Bearer tts-.... Esta clave es única por cuenta y se utiliza en cada solicitud POST al endpoint de síntesis. Asegúrate de mantenerla en un lugar seguro, ya que concede acceso directo a tu saldo.
El formato es estricto y compatible con las librerías HTTP estándar. No necesitas generar tokens adicionales ni realizar procesos de OAuth adicionales para cada petición; la clave proporcionada en tu panel es suficiente para autorizar todas las solicitudes de audio.
Rotación de claves si es necesario
Puedes generar una nueva clave en cualquier momento desde tu panel de control. Al emitir una nueva, la clave anterior deja de funcionar de inmediato, lo que permite revocar el acceso rápidamente si se compromete o si cambias de entorno de desarrollo.
Este proceso es instantáneo y no requiere reinicios ni esperas. Es útil para separar claves de producción de las de pruebas o para distribuir credenciales a diferentes miembros de una agencia sin afectar el saldo ni la configuración de la cuenta.
Primera solicitud con cURL
Para iniciar, envía una solicitud POST a https://api.chasus33.info/v1/audio/speech. El cuerpo JSON requiere el campo model ("tts-1" o "tts-1-hd") y input con el texto a narrar. Los modelos comparten el mismo motor y precio, garantizando coherencia en la producción de video.
La API procesa el texto y devuelve el archivo de audio directamente en la respuesta. Para textos largos, se recomienda dividir el contenido en fragmentos de máximo 4096 caracteres y unir los archivos resultantes posteriormente.
Endpoint POST /v1/audio/speech
Utiliza el método POST hacia la ruta /v1/audio/speech de la API base. Incluye el encabezado Authorization: Bearer <tu-clave> para autenticar la solicitud.
Body JSON con modelo e input
El cuerpo de la petición debe contener obligatoriamente model e input. Puedes añadir opcionalmente voice, speed y response_format para personalizar la salida según el estilo de tu video.
El campo input acepta hasta 4096 caracteres por solicitud. El texto se genera de forma síncrona, pero puede esperar en cola bajo carga.
- Modelos: tts-1, tts-1-hd
- Input: máximo 4096 caracteres
- Voice: uno de los 8 presets
- Speed: 0.25 a 4.0
Recibición del archivo de audio
La respuesta contiene el archivo de audio binario en el formato solicitado. Si la síntesis falla, no se cobra el crédito y la respuesta indica el error.
Guarda el archivo en tu servidor o flujo de trabajo de edición. El tiempo de generación es aproximadamente tiempo real para textos extensos.
Uso con SDK de OpenAI
Integrar VozNarradora con el ecosistema de OpenAI es inmediato: solo necesitas ajustar la URL base en tu configuración SDK a https://api.chasus33.info/v1. Esto permite reutilizar el código y la lógica de tus proyectos actuales sin reescribir la capa de red.
Las librerías oficiales funcionan correctamente al apuntar a este endpoint, manteniendo la misma estructura de cuerpo JSON. Solo recuerda actualizar tu clave Bearer en los encabezados de autorización para garantizar que las solicitudes sean autenticadas correctamente por nuestro sistema.
Cambio de base_url a api.chasus33.info
Configura tu cliente SDK estableciendo la URL base en https://api.chasus33.info/v1. Este cambio redirige las peticiones directamente a nuestra infraestructura sin alterar la lógica de tu aplicación.
Una vez ajustada la URL, las llamadas a la función de generación de voz utilizarán nuestros servidores para el procesamiento del audio.
Compatible con librerías oficiales
Las librerías oficiales de OpenAI son totalmente compatibles con nuestra API al modificar la base URL. Puedes utilizar las mismas herramientas de desarrollo que ya conoces para integrar narración en tus flujos de trabajo.
Esta compatibilidad reduce la curva de aprendizaje, permitiendo que los desarrolladores generen audio sin aprender una nueva sintaxis de petición.
Mismo formato de solicitud
El cuerpo de la solicitud JSON mantiene la misma estructura que el endpoint de OpenAI. Solo necesitas proporcionar los parámetros estándar como modelo, entrada de texto y voz.
No es necesario modificar la estructura de los datos enviados; el sistema interpretará tus parámetros correctamente para generar el archivo de audio final.
Parámetros de la solicitud
La API acepta dos identificadores de modelo: tts-1 y tts-1-hd. Ambos utilizan exactamente el mismo motor de síntesis y tienen el mismo costo por carácter, por lo que la elección no afecta la calidad del audio ni el precio final.
El campo model debe enviarse como una cadena de texto en el cuerpo JSON de la solicitud POST. No hay diferencias técnicas visibles entre las dos opciones para el cliente final.
Modelos: tts-1 y tts-1-hd
La API acepta dos identificadores de modelo: tts-1 y tts-1-hd. Ambos utilizan exactamente el mismo motor de síntesis y tienen el mismo costo por carácter, por lo que la elección no afecta la calidad del audio ni el precio final.
El campo model debe enviarse como una cadena de texto en el cuerpo JSON de la solicitud POST. No hay diferencias técnicas visibles entre las dos opciones para el cliente final.
tts-1tts-1-hd
Voces disponibles (lista de 8)
El parámetro voice requiere uno de los ocho presets disponibles. Cada voz tiene un tono definido para diferentes tipos de contenido, desde narraciones claras hasta locuciones promocionales energéticas.
Todas las voces pueden hablar los 23 idiomas soportados. Si no se especifica language, el sistema intenta adivinarlo basándose en el script, aunque se recomienda establecerlo explícitamente para textos en latinos fuera del inglés.
- aria (femenina, narradora clara)
- nova (femenina, brillante)
- luna (femenina, suave)
- sage (femenina, instruccional)
- felix (masculino, enérgico)
- milo (masculino, conversacional)
- atlas (masculino, neutral)
- orion (masculino, documental)
Velocidad ajustable de 0.25 a 4.0
El campo speed permite ajustar la velocidad de narración entre 0.25 y 4.0. El valor predeterminado es 1.0.
Para videos de YouTube, ajustar la velocidad puede ayudar a mantener el ritmo del contenido sin alterar la entonación de la voz seleccionada.
Formatos de salida soportados
La API devuelve el audio en el formato solicitado directamente en la respuesta de la solicitud POST. El formato elegido afecta el tamaño del archivo y la compatibilidad con tus herramientas de edición de video o plataformas de distribución.
Selecciona el formato adecuado según tu flujo de trabajo. MP3 es ideal para la mayoría de los usos en YouTube, mientras que WAV o FLAC son preferibles si necesitas mantener la máxima fidelidad de audio antes de la exportación final.
MP3 para web y video
El formato MP3 es la opción estándar para la mayoría de los creadores de contenido. Ofrece una buena relación entre calidad y tamaño de archivo, lo que facilita la carga en plataformas como YouTube y la integración en videos editados.
WAV para alta calidad
El formato WAV proporciona audio sin pérdida, manteniendo la fidelidad original de la síntesis. Es recomendable si tu flujo de trabajo de postproducción requiere archivos de alta calidad sin compresión, o si vas a aplicar efectos de audio adicionales en tu software de edición.
OPUS, FLAC y PCM para procesamiento
Los formatos OPUS y FLAC ofrecen compresión con pérdida y sin pérdida respectivamente, útiles para optimización de almacenamiento o procesamiento posterior. PCM es un formato sin comprimir que proporciona los datos de audio crudos, ideal para análisis técnico o integraciones que requieren datos de audio sin codificar.

Manejo de errores comunes
La API devuelve códigos de estado HTTP claros para facilitar la depuración en entornos de producción automatizada. Los errores más frecuentes están relacionados con la autenticación, los límites de velocidad o la estructura del cuerpo de la solicitud.
Error 401 por clave inválida
Este error indica que la cabecera Authorization: Bearer contiene una clave inexistente o expirada. Verifica que estás usando la clave generada en /get-api-key/ y que no haya espacios adicionales al copiarla.
Error 429 por límite de velocidad
Se activa al superar las 60 solicitudes por minuto (o 10 si no se ha realizado un recargo de saldo). Implementa una lógica de reintentos con backoff exponencial para evitar bloqueos durante picos de generación de voz.
Errores de cuerpo JSON malformado
La API exige un JSON estricto con los campos model, input y voice. Asegúrate de que el texto no supere los 4096 caracteres y que los valores de velocidad estén entre 0.25 y 4.0.
Límites y velocidad de la API
La API está diseñada para gestionar cargas de trabajo variables, pero requiere atención a los límites de tasa para asegurar una entrega predecible. Cada clave API está sujeta a un máximo de 60 solicitudes por minuto una vez que la cuenta está activa y con saldo.
Para cuentas nuevas sin recarga de saldo, el límite inicial se reduce a 10 solicitudes por minuto. Esta restricción evita saturación durante la fase de prueba y se eleva automáticamente tras la primera recarga.
60 solicitudes por minuto por clave
Una vez que tu cuenta está activa y ha recibido una recarga mínima, el límite estándar es de 60 solicitudes por minuto. Este volumen es suficiente para la mayoría de flujos de trabajo de generación de audio en lotes moderados.
Límite inicial de 10 req/min
Al crear una cuenta nueva sin recargar saldo, el límite se reduce a 10 solicitudes por minuto. Esta restricción se mantiene hasta que se realice la primera recarga de saldo, garantizando un uso controlado durante la prueba gratuita.
Cola de procesamiento bajo carga
Las solicitudes se procesan de forma secuencial. En momentos de alta demanda, una solicitud puede esperar en una cola antes de comenzar la síntesis. Esto puede aumentar ligeramente el tiempo de respuesta total, pero no afecta la calidad del audio generado.
Ejemplo de código Python
Para integrar la API de VozNarradora en tu flujo de trabajo de producción de videos, lo más sencillo es utilizar la librería estándar requests de Python. Este enfoque evita dependencias pesadas y te permite gestionar las solicitudes HTTP directamente, lo cual es ideal para scripts de automatización que procesan guiones largos.
El proceso implica construir el encabezado con tu clave Bearer y enviar el texto al endpoint correspondiente. Al recibir la respuesta, el archivo de audio se guarda en disco para su posterior edición o subida a plataformas como YouTube.
Instalación de librería requests
Asegúrate de tener instalado el paquete requests. Puedes instalarlo ejecutando pip install requests en tu entorno de desarrollo. Esta librería es ligera y suficiente para las necesidades básicas de la API.
Configuración de headers y auth
Define la URL base como https://api.chasus33.info/v1 y establece el encabezado Authorization con tu clave Bearer. Asegúrate de que el cuerpo de la solicitud incluya el modelo tts-1 o tts-1-hd, el texto a narrar y la voz deseada.
- Authorization: Bearer tts-tu_clave_aqui
- Content-Type: application/json
Envío y guardado del archivo
Realiza la petición POST y verifica que el estado sea 200. Guarda el contenido binario de la respuesta en un archivo local con el formato seleccionado (mp3, wav, etc.). Este archivo estará listo para ser incrustado en tu video.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. Para producciones de escala, esto implica que la elección del preset debe anticipar el tono necesario sin depender de ajustes finos post-generación.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
