Preguntas frecuentes
¿Qué es el endpoint POST /v1/audio/speech?
Es el punto final principal para enviar texto y recibir un archivo de audio. Recibe un cuerpo JSON con campos como model, input, voice y response_format. Sigue la misma estructura que el endpoint de speech de OpenAI, lo que facilita su integración en flujos de trabajo existentes sin necesidad de adaptar la lógica de la solicitud.
¿Cómo se configura la base_url para OpenAI SDK?
Debes cambiar la propiedad base_url de tu cliente OpenAI a https://api.playt833.com/v1. Luego, utiliza la clave API de CantoAnim en lugar de la de OpenAI. Esto permite que los SDKs oficiales de OpenAI funcionen correctamente con nuestra infraestructura, manteniendo la misma forma de solicitud que el endpoint de speech estándar.
¿Qué voces están disponibles en la API?
Hay 8 voces preestablecidas: Aria, Nova, Luna y Sage (femeninas); Felix, Milo, Atlas y Orion (masculinas). Cada una tiene un tono distintivo, desde narrador cálido hasta voz de documental. Todas las voces pueden hablar cualquiera de los 23 idiomas soportados, permitiendo flexibilidad para asignar personajes sin importar su género o acento.
¿Cuál es la diferencia entre tts-1 y tts-1-hd?
Ambos modelos utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. La única diferencia es el nombre del modelo en la solicitud. Puedes usar 'tts-1' o 'tts-1-hd' indistintamente, ya que el resultado de audio y la velocidad de generación son idénticos para ambos casos.
¿Qué formatos de audio son soportados?
La API soporta los formatos mp3, wav, opus, flac y pcm. Debes especificar el formato deseado en el campo response_format de tu solicitud JSON. Estos formatos cubren necesidades desde reproducción web hasta edición profesional, permitiendo elegir la compresión o calidad adecuada según el flujo de trabajo de producción de tu estudio o startup.
¿Cuántas solicitudes puedo hacer por minuto?
El límite es de 60 solicitudes por minuto por clave API. Antes de la primera recarga, el límite es de 10 solicitudes por minuto. Si excedes este límite, las solicitudes se procesarán en cola o recibirán un error. Esto asegura que la generación de audio mantenga una velocidad constante y predecible para todos los usuarios.
¿Qué ocurre si excedo el límite de caracteres?
Cada solicitud puede contener hasta 4096 caracteres en el campo input. Si tu texto es más largo, debes dividirlo en partes de este tamaño y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres. Esta limitación garantiza un procesamiento eficiente y consistente para cada solicitud individual enviada al endpoint.
¿La API devuelve audio en streaming?
No. La API devuelve el archivo de audio completo en la respuesta tras la síntesis. No hay streaming, WebSockets ni audio parcial en tiempo real. Debes esperar a que se complete la generación antes de recibir el archivo. Esto es consistente con el modelo de solicitud-respuesta estándar que sigue la estructura del endpoint de speech.
¿Cómo se manejan los errores de rate limit?
Si excedes los 60 o 10 límites por minuto, la solicitud puede fallar o esperar en cola. Las solicitudes fallidas son gratuitas y el cargo se devuelve íntegramente. Implementa lógica de reintento con retroceso exponencial en tu código para manejar estos casos de forma robusta, asegurando que tu aplicación no se detenga completamente por picos de tráfico.
¿Puedo usar la misma clave en múltiples proyectos?
Sí, puedes usar la misma clave API en múltiples proyectos o servicios. Cada cuenta tiene una clave activa que se puede revocar y emitir una nueva si es necesario. La clave autentica todas las solicitudes, independientemente del origen, permitiendo centralizar la facturación y el control de acceso para todos tus servicios de generación de voz.
¿Qué pasa si se revoca una clave API?
Si emites una nueva clave, la anterior deja de funcionar inmediatamente. No hay período de gracia. Asegúrate de actualizar todas tus aplicaciones y servicios que utilicen la clave antigua antes o justo en el momento de la renovación. Esto garantiza que no haya interrupciones en la generación de audio durante el cambio de credenciales.
¿Los archivos de audio se almacenan en la API?
No. Los archivos de audio generados se devuelven en la respuesta y no se almacenan en nuestros servidores. Solo se conservan los metadatos de la solicitud (tiempo, caracteres, estado) para facturación. El texto de entrada se usa únicamente para producir el audio y no se utiliza para entrenar modelos, garantizando la privacidad de tu contenido.
¿Se puede especificar el idioma manualmente?
Sí, puedes usar el campo language con un código ISO para forzar un idioma. Si no se especifica, el sistema intenta adivinarlo basándose en el script, asumiendo inglés para texto en latín. Es recomendable establecer el idioma explícitamente para textos en latín que no sean inglés, asegurando la pronunciación correcta de los personajes en tu producción.
¿Qué es el campo 'input' en la solicitud?
Es el campo que contiene el texto que deseas convertir a voz. Debe tener un máximo de 4096 caracteres. Este texto se procesa mediante el modelo seleccionado para generar el audio. Incluye espacios y puntuación en el conteo de caracteres, lo cual afecta directamente el costo de la solicitud según la tarifa por carácter de CantoAnim.
Primera solicitud
curl
curl https://api.playt833.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playt833.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.playt833.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 | |
|---|---|
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
Para comenzar a integrar nuestra API de texto a voz, accede a /get-api-key/ y regístrate mediante Google o correo electrónico. Este paso crea tu cuenta independiente en playt833.com y habilita el acceso a la clave de autenticación necesaria para las solicitudes.
Una vez registrado, el sistema genera un token único que autoriza el uso del servicio. Mantén este valor seguro, ya que es el identificador principal para todas tus llamadas a la API.
Registro en /get-api-key/
Visita la página de registro y elige tu método de preferencia: Google o correo electrónico. Si usas Google, recibirás un bono de prueba inicial de $0.50 válido por 7 días. Los registros por email no incluyen este crédito inicial.
- Registro instantáneo con Google o email
- Crédito de prueba disponible para cuentas de Google
- Cuenta vinculada específicamente a playt833.com
Visualización de la clave activa
Después del registro, tu panel mostrará la clave API activa en formato tts-.... Esta credencia es necesaria para autenticar cada solicitud enviada al endpoint. Puedes ver también tu saldo actual y el historial de uso.
- Clave visible inmediatamente tras el registro
- Formato estándar
tts-... - Visualización en tiempo real del saldo
Renovación de la clave
Si necesitas generar una nueva clave, puedes hacerlo en cualquier momento desde tu panel. La clave antigua deja de funcionar inmediatamente al emitir la nueva, garantizando que solo tengas un token activo por cuenta.
- Renovación instantánea
- La clave anterior se invalida al instante
- Sin interrupción en el servicio si se usa la nueva clave
Primera solicitud con cURL
Para iniciar, envía una solicitud POST a https://api.playt833.com/v1/audio/speech. El cuerpo debe ser JSON con el texto a sintetizar y la voz elegida. La respuesta devuelve el archivo de audio directamente.
Estructura del cuerpo JSON
El cuerpo de la solicitud debe contener el campo input con el texto (máx. 4096 caracteres), model ("tts-1" o "tts-1-hd") y voice (ej. "nova"). Puedes especificar response_format (mp3, wav, opus, flac, pcm) y speed (0.25–4.0).
Parámetros requeridos
Los campos obligatorios son model, input y voice. La autenticación se realiza mediante el encabezado Authorization: Bearer tu-clave-api. Si no especificas language, el sistema intenta adivinarlo por el script, pero se recomienda definirlo explícitamente para textos en latinos fuera del inglés.
- model: "tts-1" o "tts-1-hd"
- input: texto hasta 4096 caracteres
- voice: una de las 8 presets (ej. "aria", "felix")
- Authorization: Bearer clave_api
Ejemplo de respuesta exitosa
Si la síntesis es exitosa, recibirás un código de estado 200 con el archivo de audio binario en el cuerpo de la respuesta. No se almacena audio generado; solo se devuelve al instante. El consumo de caracteres se deduce de tu saldo o prueba gratuita.
Uso con SDK de OpenAI
Nuestra API de texto a voz sigue la misma estructura de solicitud que el endpoint de speech de OpenAI. Esto permite reutilizar tus SDKs y bibliotecas existentes sin necesidad de aprender una nueva sintaxis o lógica de integración.
Al cambiar la URL base, puedes generar audio con modelos compatibles mediante código familiar, manteniendo la misma estructura de cuerpo JSON y autenticación que ya conoces.
Cambio de base_url
Modifica la propiedad base_url en tu cliente SDK para apuntar a https://api.playt833.com/v1. Esta configuración dirige las solicitudes al servicio correcto sin alterar la lógica de tu aplicación.
- Base URL:
https://api.playt833.com/v1
Compatibilidad con endpoints
El endpoint POST /v1/audio/speech acepta el mismo cuerpo de solicitud que el servicio original. Esto incluye los campos model, input, voice, response_format y speed.
Configuración de autenticación
Envía tu clave API en el encabezado Authorization: Bearer tts-.... Esta clave se genera en la página de registro y es necesaria para cada solicitud de síntesis.
Parámetros de la solicitud
La estructura JSON de tu solicitud se envía al endpoint POST /v1/audio/speech. Debes especificar el modelo, el texto a sintetizar, la voz deseada y el formato de audio. Estos campos determinan cómo se procesará tu solicitud y cómo recibirás el resultado.
Los parámetros son estrictos: el texto no puede exceder 4096 caracteres por llamada. Si necesitas generar audio más largo, deberás dividir el texto y unir los archivos resultantes. La velocidad se ajusta entre 0.25 y 4.0.
Modelo tts-1 y tts-1-hd
El campo model acepta dos valores: tts-1 o tts-1-hd. Ambos utilizan el mismo motor de síntesis y tienen el mismo precio por carácter. No hay diferencia técnica en la calidad del audio entre ambos, solo en la denominación del modelo en la API.
Selección de voz
El parámetro voice requiere uno de los 8 presets disponibles. Cada voz tiene un tono específico para diferentes contextos de animación. Por ejemplo, usa aria para narradoras cálidas, nova para personajes brillantes, luna para historias suaves, sage para instrucciones calmadas, felix para promos dinámicas, milo para diálogos conversacionales, atlas para noticias neutrales o orion para documentales profundos.
- Aria: narradora cálida y clara
- Nova: brillante y enérgica
- Luna: suave para historias
- Sage: calmada e instructiva
- Felix: dinámica para promos
- Milo: conversacional y amigable
- Atlas: neutral para noticias
- Orion: profunda para documentales
Formato de respuesta
Especifica el formato de audio con response_format. Las opciones son mp3, wav, opus, flac y pcm. Elige el formato que mejor se integre con tu pipeline de postproducción de audio. Los archivos generados contienen una marca de agua inaudible que los identifica como sintetizados.
- mp3
- wav
- opus
- flac
- pcm
Límites y rendimiento
La API está diseñada para procesamiento secuencial, lo que garantiza consistencia pero implica que las solicitudes se procesan una tras otra. Conocer estos límites es clave para integrar la generación de voz en flujos de trabajo de animación sin bloqueos inesperados.
El sistema gestiona la carga de manera predecible, permitiendo a los estudios planificar la generación de diálogos para múltiples personajes sin sorpresas en la facturación ni cortes abruptos de servicio.
60 solicitudes por minuto
El límite estándar es de 60 solicitudes por minuto por clave API. Antes de la primera recarga de saldo, este límite se reduce a 10 solicitudes por minuto para cuentas nuevas.
- 60 req/min con saldo activo
- 10 req/min antes del primer top-up
- Límite por clave activa, no por IP
Límite de 4096 caracteres
Cada solicitud soporta hasta 4096 caracteres de texto, incluyendo espacios y puntuación. Para diálogos más largos, debes dividir el texto y unir los archivos de audio resultantes.
Cola de procesamiento
Las solicitudes se procesan en orden secuencial. Bajo alta carga, una solicitud puede esperar en cola antes de comenzar la síntesis, lo que añade latencia pero no afecta el precio final.

Manejo de errores comunes
La API devuelve códigos HTTP claros para que integres el manejo de errores en tu pipeline de animación sin interrupciones. Cada respuesta indica si la síntesis falló, permitiendo reintentos o ajustes inmediatos en el flujo de trabajo de audio.
Error de autenticación
Si el token es inválido o expiró, recibirás un error 401. Asegúrate de que la cabecera Authorization: Bearer tts-... coincida exactamente con la clave activa en tu panel.
- Código HTTP: 401 Unauthorized
Límite de caracteres excedido
La API rechaza textos de más de 4096 caracteres con un error 400. Divide el guion en fragmentos y únelos después para evitar cortes inesperados en la generación.
- Código HTTP: 400 Bad Request
Formato de audio inválido
Si solicitas un formato no soportado (distinto a mp3, wav, opus, flac o pcm), recibirás un error 400. Verifica que el campo response_format esté escrito correctamente.
- Código HTTP: 400 Bad Request
Generación de textos largos
La API TTS de CantoAnim acepta un máximo de 4096 caracteres por solicitud. Para proyectos de animación que requieren diálogos extensos, es necesario dividir el texto en fragmentos que respeten este límite. Cada fragmento genera un archivo de audio independiente.
Los archivos generados deben unirse en el lado del cliente para mantener la sincronización con la animación. Utiliza estrategias de buffering para almacenar temporalmente los fragmentos antes de concatenarlos en un solo archivo final, garantizando que no se pierda tiempo de espera durante la reproducción.
División en partes de 4096 caracteres
Cada solicitud POST solo procesa hasta 4096 caracteres. Si tu guion supera este límite, divide el texto en segmentos lógicos (por ejemplo, por oración o frase) para evitar errores de validación.
El límite incluye espacios y puntuación. Asegúrate de que cada fragmento sea independiente para que la síntesis sea rápida y predecible.
- Máximo 4096 caracteres por request.
- Incluye espacios y signos de puntuación en el conteo.
- Divide el guion en segmentos manejables.
Unión de archivos de audio
La API devuelve un archivo de audio por fragmento procesado. Es responsabilidad del desarrollador concatenar estos archivos en el orden correcto.
Utiliza bibliotecas de audio estándar en tu lenguaje de programación para unir los fragmentos sin introducir pausas silenciosas entre ellos, manteniendo la fluidez del diálogo.
- Procesa fragmentos en orden secuencial.
- Concátalos en el lado del cliente.
- Evita pausas entre segmentos unidos.
Estrategias de buffering
Implementa un buffer para almacenar los fragmentos de audio a medida que llegan. Esto permite iniciar la reproducción antes de que todos los fragmentos estén completamente procesados.
Optimiza la memoria del cliente para manejar varios fragmentos simultáneamente, especialmente útil en secuencias largas de animación donde la latencia debe ser mínima.
- Almacena fragmentos en memoria temporal.
- Inicia la reproducción anticipadamente.
- Reduce la latencia percibida.
Ejemplos de código completos
Estos ejemplos muestran cómo implementar la integración directa con la API de CantoAnim. Puedes usarlos como punto de partida para tus pipelines de animación o prototipos en startups.
Los fragmentos cubren la autenticación básica y las llamadas estándar, asegurando que recibas el archivo de audio sin complicaciones adicionales.
Script Python básico
Utiliza la librería requests para enviar el texto y recibir el audio binario. Asegúrate de manejar la respuesta como un archivo .mp3 o .wav según tu preferencia.
Este enfoque es ideal para scripts de automatización que generan voces para personajes sin dependencias de SDKs pesados.
- Instala dependencias:
pip install requests - Configura la URL base y la clave Bearer
- Guarda la respuesta
contenten un archivo local
Configuración en JavaScript
Usa fetch para realizar la solicitud POST. Es crucial definir el encabezado Authorization correctamente y parsear la respuesta como blob para conservarla.
Ideal para aplicaciones web o Node.js que necesitan generar audio bajo demanda durante la renderización de escenas.
Headers de autenticación
La clave API debe enviarse en el encabezado Authorization: Bearer tts-tu_clave_aqui. Asegúrate de que no haya espacios extra.
Si la clave es incorrecta o ha expirado, recibirás un error 401. Renueva tu clave desde /get-api-key/ si es necesario.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
