Preguntas frecuentes
¿Cómo obtengo mi clave API?
Regístrese en /get-api-key/ con Google o correo electrónico. La página muestra su clave activa, saldo y ejemplos de uso. Cada cuenta tiene una clave activa por sitio. Puede emitir una nueva clave en cualquier momento, lo que invalida la anterior inmediatamente.
¿Qué es la base_url para el SDK de OpenAI?
La base_url es https://api.68ok.info/v1. Configure esta URL en el SDK de OpenAI para usar sus bibliotecas oficiales. El formato de solicitud es idéntico al endpoint de voz de OpenAI.
¿Cuál es el límite de caracteres por petición?
El límite es de 4096 caracteres por solicitud. Si el texto excede este límite, debe dividirlo en partes y unir los archivos de audio resultantes. Los espacios y la puntuación cuentan como caracteres. Esto garantiza que cada solicitud de síntesis se procese correctamente.
¿Qué modelos de voz están disponibles?
Existen 8 voces preestablecidas: aria, nova, luna, sage, felix, milo, atlas y orion. Puede seleccionar cualquiera mediante el campo voice en la solicitud JSON. Todas las voces pueden hablar los 23 idiomas soportados sin necesidad de cambiar el modelo subyacente.
¿Cómo se ajusta la velocidad de voz?
Use el campo speed en la solicitud, con un rango de 0.25 a 4.0. El valor predeterminado es 1.0. Ajustar la velocidad permite adaptar la generación de audio a diferentes contextos, como anuncios rápidos o narraciones detalladas, sin afectar la calidad del audio.
¿Qué formato de audio es mejor para tiendas?
Puede elegir entre mp3, wav, opus, flac o pcm. El formato mp3 es adecuado para la mayoría de las tiendas por su equilibrio entre calidad y tamaño. El formato wav ofrece sin compresión. La elección depende de sus requisitos de almacenamiento y compatibilidad del reproductor.
¿Cómo manejo errores de la API?
Las solicitudes fallidas son gratuitas y el cargo se devuelve íntegramente. Si la síntesis falla, no se le cobra. Verifique que el texto esté dentro del límite de 4096 caracteres y que la clave API sea válida. Los errores comunes suelen ser de formato JSON o autenticación.
¿Cuántas solicitudes puedo hacer por minuto?
El límite es de 60 solicitudes por minuto por clave. Antes del primer recargo, el límite es de 10 solicitudes por minuto. Las solicitudes se procesan en cola, por lo que bajo carga puede haber retrasos. Monitoree su uso en el panel de control para evitar límites.
¿Se puede personalizar la voz?
No se ofrece clonación de voz personalizada ni diseño de voz. Solo hay 8 voces preestablecidas disponibles. No se pueden subir grabaciones propias ni ajustar parámetros de emoción o tono más allá de la velocidad. La personalización se limita a seleccionar entre las voces existentes en la API.
¿Qué pasa si excedo el límite de caracteres?
Si el texto excede 4096 caracteres, la solicitud fallará o debe dividirse manualmente. Debe dividir el texto en partes más pequeñas y unir los archivos de audio resultantes. Esto asegura que cada chunk se sintetice correctamente. El límite es estricto por petición, no por sesión.
¿Cómo se detecta el idioma automáticamente?
Si no se especifica el campo language, el sistema intenta adivinarlo basado en el script. El texto en latino por defecto se asume inglés. Para otros idiomas en latín, debe establecer explícitamente el campo language con el código ISO para evitar errores de pronunciación.
¿Necesito instalar un plugin para usar la API?
No, no es necesario instalar ningún plugin. La API funciona mediante llamadas HTTP POST estándar. Puede usar bibliotecas de OpenAI o cualquier cliente HTTP. Esto permite una integración flexible en cualquier entorno que pueda realizar solicitudes web.
¿Es compatible con WordPress?
No hay un plugin oficial de WordPress. Sin embargo, puede usar la API mediante llamadas HTTP desde PHP o JavaScript en su tema. Puede crear una integración personalizada para generar audios en catálogos o notificaciones. La compatibilidad depende de su capacidad para realizar solicitudes web.
¿Cómo se emite una nueva clave API?
Puede emitir una nueva clave desde la página de configuración de su cuenta. Al generar una nueva, la clave anterior deja de funcionar inmediatamente. Esto permite revocar accesos rápidamente si es necesario. Solo hay una clave activa por cuenta en cualquier momento.
Primera solicitud
curl
curl https://api.68ok.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.68ok.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.68ok.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
Acceder a la API requiere registrar una cuenta en /get-api-key/ mediante Google o email. La clave única se genera automáticamente y se visualiza en el panel de control junto al saldo y el historial de uso.
Registro con Google o email
El registro inicial es inmediato. Las cuentas creadas con Google incluyen un saldo de prueba de $0.50 válido por 7 días. Las cuentas con email y contraseña comienzan sin crédito de prueba.
Ubicación de la clave en el panel
La clave API (formato tts-...) se muestra en la sección de credenciales del panel. Es el único token necesario para autenticar las solicitudes HTTP mediante el encabezado Authorization: Bearer.
Emisión de nueva clave
Puede emitir una nueva clave en cualquier momento desde el panel. Al generar una nueva, la clave anterior deja de funcionar inmediatamente, lo que asegura que solo una clave esté activa por cuenta.
Primera solicitud con curl
La generación de audio mediante cURL es el método más directo para validar la integración antes de implementar la solución en el sistema de la tienda. Este comando envía una solicitud POST al endpoint principal con las credenciales y los parámetros necesarios para la síntesis.
La respuesta devuelve el archivo de audio en el cuerpo de la respuesta. Este enfoque permite probar la funcionalidad mediante una llamada HTTP estándar.
Comando POST estándar
Utilice el método HTTP POST dirigido a https://api.68ok.info/v1/audio/speech. La autenticación se realiza mediante un encabezado Authorization con un token Bearer. Es fundamental incluir la clave API válida para que la solicitud sea procesada.
- Método: POST
- URL: https://api.68ok.info/v1/audio/speech
- Encabezado: Authorization: Bearer tts-tu_clave_aqui
Cuerpo JSON requerido
El cuerpo de la solicitud debe ser un objeto JSON que contenga al menos el campo input con el texto a sintetizar. También debe especificar el modelo deseado (tts-1 o tts-1-hd) y la voz a utilizar. Los campos opcionales incluyen response_format, speed y language para ajustar el resultado final.
- model: "tts-1" o "tts-1-hd"
- input: texto máximo 4096 caracteres
- voice: nombre de la voz (ej. "aria")
- response_format: "mp3", "wav", "opus", "flac" o "pcm"
Ejemplo de respuesta exitosa
Una respuesta correcta devuelve un código de estado HTTP 200 con el archivo de audio binario en el cuerpo. El formato del archivo coincide con el solicitado en el campo response_format. Si la síntesis falla, se devuelve un código de error y la carga no se descuenta del saldo.
Uso con SDK de OpenAI
La integración con las librerías de OpenAI permite utilizar la API VozTextil modificando la URL base. Solo es necesario ajustar la configuración de conexión para apuntar a nuestros servidores, manteniendo la misma estructura de peticiones y respuestas que conoce.
Este enfoque reduce el tiempo de desarrollo al reutilizar el código existente. Los desarrolladores pueden generar audios utilizando las mismas herramientas que emplean para otros servicios.
Cambio de base_url
Para conectar con VozTextil, modifique la propiedad base_url de su cliente SDK para apuntar a https://api.68ok.info/v1. Esta dirección es la ruta base para todas las llamadas API, incluyendo la generación de audio y la consulta de voces disponibles.
Al realizar este cambio, el SDK dirigirá las peticiones a nuestra infraestructura en lugar de los servidores de OpenAI, permitiendo el uso de la misma sintaxis JSON para enviar texto y recibir archivos de audio.
- URL base: https://api.68ok.info/v1
- Método estándar compatible
Compatibilidad con librerías oficiales
La API sigue la misma estructura de solicitud que el endpoint de voz de OpenAI. Esto significa que las librerías oficiales de Python, Node.js y otros lenguajes funcionan sin adaptadores adicionales.
Solo necesita asegurarse de que la versión de la librería sea compatible con los parámetros model, input, voice y response_format descritos en la documentación de los parámetros de la solicitud.
Configuración de autenticación
La autenticación se realiza mediante una clave Bearer en el encabezado Authorization. Esta clave se genera en la página /get-api-key/ y debe incluirse en todas las solicitudes para evitar errores 401.
Recuerde que puede emitir una nueva clave en cualquier momento desde el panel; la clave anterior dejará de funcionar inmediatamente, por lo que debe actualizarla en su código de integración si decide rotarla.
Endpoints disponibles
La API de VozTextil expone tres endpoints RESTful principales para la integración en tiendas online. Cada endpoint devuelve datos en formato JSON estandarizado, facilitando la lectura automática por sistemas sin código.
Los clientes pueden generar audio, consultar la disponibilidad de voces y verificar los modelos disponibles mediante solicitudes HTTP simples, sin necesidad de descargar bibliotecas adicionales.
Generación de audio /v1/audio/speech
Este es el endpoint principal para la síntesis de voz. Recibe una solicitud POST con el texto a convertir y devuelve el archivo de audio generado directamente en la respuesta. Los formatos soportados incluyen mp3, wav, opus, flac y pcm.
La estructura de la petición es idéntica a la de OpenAI, lo que permite utilizar sus SDKs oficiales modificando únicamente la base URL. El texto de entrada se limita a 4096 caracteres por solicitud.
- Endpoint: POST /v1/audio/speech
- Formatos: mp3, wav, opus, flac, pcm
Listado de voces /v1/voices
La ruta GET /v1/voices devuelve un listado de todas las voces disponibles, junto con sus idiomas soportados y formatos de audio compatibles. Esto permite a las tiendas configurar dinámicamente las opciones de voz para sus catálogos.
Se pueden consultar las 8 voces preestablecidas (aria, nova, luna, sage, felix, milo, atlas, orion) sin necesidad de conocer sus nombres de antemano, facilitando la integración en formularios de selección de voz.
- Endpoint: GET /v1/voices
- Incluye: voces, idiomas, formatos
Información de modelos /v1/models
El endpoint GET /v1/models proporciona información técnica sobre los motores de síntesis disponibles, específicamente tts-1 y tts-1-hd. Ambos utilizan el mismo motor y tienen el mismo precio, diferenciándose principalmente por la calidad de audio.
Esta información es útil para verificar la disponibilidad de los modelos en tiempo real antes de realizar la generación de audio, asegurando la compatibilidad con la infraestructura actual de la tienda.
- Endpoint: GET /v1/models
- Modelos: tts-1, tts-1-hd
Parámetros de la solicitud
La generación de audio requiere especificar un modelo en el cuerpo de la solicitud. El sistema acepta únicamente los valores "tts-1" o "tts-1-hd", los cuales utilizan el mismo motor de síntesis y tienen un precio idéntico, independientemente de la elección.
Modelo tts-1 y tts-1-hd
Ambos modelos utilizan el mismo motor de síntesis. La selección no afecta el costo ni la velocidad de procesamiento, permitiendo elegir según la compatibilidad de la librería utilizada.
Input de texto hasta 4096 caracteres
El campo input acepta cadenas de texto de hasta 4096 caracteres por solicitud. Se recomienda dividir textos más largos para mantener la coherencia de la síntesis y evitar cortes abruptos en la generación de audio.
- Los espacios y la puntuación cuentan como caracteres.
- Máximo 4096 caracteres por llamada HTTP.
Voz, idioma y formato de respuesta
Debe especificarse una voz de las ocho disponibles (por ejemplo, aria o felix). El parámetro language es opcional; si se omite, el sistema infiere el idioma, aunque para textos en latinos fuera del inglés se recomienda establecerlo explícitamente. El formato de salida puede ser mp3, wav, opus, flac o pcm.
- Voces: 8 presets predefinidos.
- Formatos: mp3, wav, opus, flac, pcm.

Límites y errores comunes
La API impone límites claros para garantizar un servicio estable. Cada clave activa permite un máximo de 60 solicitudes por minuto. Antes de realizar la primera recarga de saldo, este límite se reduce a 10 solicitudes por minuto, lo cual es suficiente para las pruebas iniciales de integración.
Los errores se manejan mediante códigos HTTP estándar. Si la síntesis falla, no se aplica ningún cargo y el saldo se devuelve íntegramente. Esto asegura que solo se pague por las solicitudes procesadas con éxito, minimizando el riesgo durante la fase de desarrollo.
60 solicitudes por minuto
El límite de 60 solicitudes por minuto se aplica por clave API. Si excede este umbral, las nuevas peticiones recibirán un error de cuota excedida hasta que el minuto se reinicie. Para tiendas con alto tráfico, esto es suficiente si se gestiona la cola adecuadamente.
- Límite estándar: 60 req/min por clave.
- Límite inicial (pre-pago): 10 req/min.
- El contador se resetea cada 60 segundos.
Manejo de errores HTTP
Las respuestas de error incluyen un código HTTP (como 429 para límite excedido o 500 para fallos internos) y un mensaje descriptivo. Es importante verificar estos códigos en su cliente para reintentar las solicitudes fallidas sin cobrar saldo innecesariamente.
Si la síntesis no se completa por un error del servidor, la carga se devuelve automáticamente. No se requiere acción manual para recuperar el crédito gastado en la solicitud fallida.
- 429: Demasiadas solicitudes (límite de velocidad).
- 500: Error interno del servidor (reintento recomendado).
- Cobro revertido automáticamente en fallos de síntesis.
Validación de caracteres
Cada solicitud de generación de audio acepta un máximo de 4096 caracteres en el campo input. Esto incluye espacios, puntuación y caracteres especiales. Si su texto supera este límite, debe dividirlo en fragmentos menores para evitar errores de validación.
El conteo de caracteres es estricto. Asegúrese de que su sistema de división de texto respete este límite antes de enviar la petición POST a la API.
- Máximo: 4096 caracteres por solicitud.
- Incluye espacios y puntuación.
- Texto excedido genera error de validación.
Formateo de texto largo
El límite de 4096 caracteres por solicitud requiere dividir textos extensos, como descripciones de productos o catálogos, en fragmentos manejables. Cada fragmento se procesa como una solicitud individual para garantizar la síntesis correcta.
Los archivos de audio generados deben concatenarse manualmente en el lado del cliente. Esta estrategia evita limitaciones de longitud y permite integrar el audio en flujos de trabajo automatizados sin depender de la API para la unión de los clips.
División en partes de 4096 caracteres
La API acepta un máximo de 4096 caracteres por llamada. Para textos más largos, como listas de inventario o avisos de envío, el cliente debe segmentar la entrada. Cada segmento se envía como una solicitud POST independiente.
Es necesario calcular la longitud del texto incluyendo espacios y puntuación. Si el texto excede el límite, la solicitud fallará. La división debe realizarse antes de la llamada a la API para mantener la integridad del mensaje.
- Límite estricto de 4096 caracteres por request.
- Contar espacios y signos de puntuación.
- Dividir antes de la llamada HTTP.
Unión de archivos de audio
La API devuelve cada fragmento como un archivo de audio separado. No existe una función nativa para unirlos en un solo archivo continuo. El cliente debe implementar la concatenación usando una librería de manejo de audio.
Este enfoque permite mayor control sobre la reproducción y la gestión de errores. Si un fragmento falla, solo ese segmento necesita ser regenerado sin afectar al resto del texto.
- Archivos de audio independientes por fragmento.
- Concatenación manual requerida en el cliente.
- Mayor control sobre la reproducción final.
Gestión de pausas
Las pausas entre fragmentos no se gestionan automáticamente por la API. Es responsabilidad del desarrollador insertar silencios o transiciones suaves entre los archivos de audio concatenados.
Para mantener la naturalidad en catálogos o anuncios, se recomienda añadir un pequeño silencio entre los segmentos unidos. Esto evita cortes abruptos y mejora la experiencia de escucha del usuario final.
El tiempo de generación es aproximadamente real, por lo que la duración total dependerá de la longitud del texto. Planificar la pausa requiere conocer la duración exacta de cada fragmento generado.
- Pausas manuales entre fragmentos.
- Silencios para transiciones naturales.
- Sin gestión automática de pausas.
Formatos de audio soportados
La API devuelve el audio en cinco formatos disponibles mediante el parámetro response_format. La elección depende del caso de uso específico dentro de la tienda online, equilibrando calidad de sonido y peso del archivo para la entrega al cliente final.
MP3 para web
El formato MP3 es la opción predeterminada y más eficiente para la mayoría de las integraciones. Ofrece compresión con pérdida, adecuada para catálogos de productos, notificaciones automáticas y anuncios promocionales.
WAV para alta calidad
WAV proporciona audio sin pérdida, preservando toda la fidelidad de la voz sintetizada. Este formato es adecuado cuando se requiere la máxima claridad de texto para grabaciones de alta precisión o integración con sistemas de audio que no soportan decodificación en tiempo real de formatos comprimidos.
Opus, FLAC y PCM
Opus ofrece compresión eficiente para almacenamiento a largo plazo con menor uso de ancho de banda. FLAC entrega compresión sin pérdida, ideal para archivar voces sin ocupar tanto espacio como WAV. PCM es audio crudo sin comprimir, útil para procesamiento posterior inmediato.
- Opus: ideal para reducir ancho de banda.
- FLAC: compresión sin pérdida para archivos.
- PCM: audio crudo sin comprimir.
Escucha las 8 voces
Cada muestra a continuación fue generada por esta API a partir de la misma frase. No requiere desarrollo complejo, lo que permite generar audios para catálogos o notificaciones de forma automática.
23 idiomas
Cualquier voz puede hablar cualquiera de estos idiomas.
