Artículo a Voz (ATS)
Convierte un artículo completo en audio narrado y una transcripción, entregados de forma asíncrona a tu URL de callback.
El endpoint de Artículo a Voz (ATS) recibe el texto de un artículo y genera una narración en MP3 junto con un archivo de transcripción sincronizada (.srt). La generación se ejecuta de forma asíncrona: la solicitud responde de inmediato con 202 Accepted y los archivos terminados se envían a la callbackURL que indiques. Este es el mismo servicio que impulsa el plugin ATS para WordPress.
No esperes el audio en la respuesta HTTP. El endpoint responde 202 de inmediato y envía el resultado mediante POST a tu callbackURL cuando termina la generación.
Autenticación
Incluye la clave de API de tu empresa como un token Bearer en el encabezado Authorization.
Authorization: Bearer your_api_key
Cuerpo de la solicitud
Envía un cuerpo JSON con el texto sin formato del artículo y un objeto postData que describa la solicitud.
| Parámetro | Obligatorio | Tipo | Descripción |
|---|---|---|---|
| text | obligatorio | string | El texto completo del artículo que se convertirá en voz. |
| postData | obligatorio | object | Metadatos de la solicitud. Consulta los campos a continuación. |
Objeto postData
| Campo | Obligatorio | Tipo | Predeterminado | Descripción |
|---|---|---|---|---|
| name | obligatorio | string | — | Título del artículo. Se usa como título de la solicitud de audio generado. |
| articleId | obligatorio | string | — | Tu identificador único para el artículo. Actúa como clave de idempotencia (consulta Idempotencia más abajo) y se devuelve en el callback. |
| voiceId | obligatorio | string | — | La voz con la que se narrará. Usa un ID de la lista de voces. Usa una voz del tipo de la clave API de tu empresa: una clave estándar usa voces estándar (voice_engine = standard) y una clave avanzada, voces avanzadas (voice_engine = advanced). Eliges el tipo al generar la clave. En ambos casos, cada oración del archivo .srt lleva tiempos palabra por palabra. |
| callbackURL | obligatorio | string (URL) | — | URL HTTPS a la que Moknah enviará mediante POST las URL del audio y la transcripción terminados. Se guarda el último valor para la empresa. |
| preprocessType | opcional | string | "0" | Modo de preparación del texto: "0" para ninguno (narrar literalmente) o "2" para tashkeel árabe (la IA añade los signos diacríticos y escribe los números con letras; duplica el costo por carácter). Se acepta como cadena o como número. "2" solo está disponible para árabe, y solo las oraciones en árabe se envían a la IA. |
| language | opcional | string | "auto" | Idioma del contenido: "auto" o un código ISO 639-1 como "ar" o "en". Con "auto", preprocessType "2" solo se usa si el texto está en árabe; de lo contrario, el artículo se narra como "0" y se cobra una sola vez. Enviar "2" con un idioma distinto del árabe se rechaza con 422 VALIDATION_ERROR. |
| regenerate | opcional | boolean | false | Cuando es true, fuerza una nueva generación aunque este articleId ya se haya generado antes. |
Ejemplo de solicitud
curl -X POST "https://api.moknah.io/process-text" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
"postData": {
"name": "AI is evolving fast",
"articleId": "post-123",
"voiceId": "12",
"callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
"preprocessType": "0",
"language": "auto",
"regenerate": false
}
}'
import requests
response = requests.post(
"https://api.moknah.io/process-text",
headers={
"Authorization": "Bearer your_api_key",
"Content-Type": "application/json"
},
json={
"text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.",
"postData": {
"name": "AI is evolving fast",
"articleId": "post-123",
"voiceId": "12",
"callbackURL": "https://your-site.com/wp-json/ats/v1/callback",
"preprocessType": "0",
"language": "auto",
"regenerate": False
}
}
)
# 202 Accepted — the audio is delivered to your callbackURL
print(response.status_code, response.text)
const response = await fetch(
'https://api.moknah.io/process-text',
{
method: 'POST',
headers: {
'Authorization': 'Bearer your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: 'الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.',
postData: {
name: 'AI is evolving fast',
articleId: 'post-123',
voiceId: '12',
callbackURL: 'https://your-site.com/wp-json/ats/v1/callback',
preprocessType: '0',
language: 'auto',
regenerate: false
}
})
}
);
// 202 Accepted — result arrives at your callbackURL
Respuesta inmediata
Si se acepta la solicitud, el endpoint responde de inmediato:
Processing started. Results will be sent to the callback URL.
Carga útil del callback
Cuando termina la generación, Moknah envía una solicitud POST a tu callbackURL con este cuerpo JSON:
{
"articleId": "post-123",
"response": {
"audioFile": "https://api-storage.moknah.io/.../******.mp3",
"srtFile": "https://api-storage.moknah.io/.../******.srt",
"signature": "<hmac-sha256-hex>"
}
}
| Campo | Descripción |
|---|---|
| articleId | El mismo articleId que enviaste en la solicitud. |
| response.audioFile | URL pública de la narración MP3 generada, o null si la generación falló. |
| response.srtFile | URL pública del archivo de transcripción sincronizada (.srt), o null si la generación falló. |
| response.signature | Firma HMAC-SHA256 que puedes usar para verificar que el payload es auténtico (ver más abajo). |
También se envía un callback cuando la generación no produce audio. En ese caso, response.audioFile y response.srtFile son null (la firma sigue cubriendo articleId|null|null). Trata cualquier callback cuyo audioFile o srtFile sea null como un fallo: no marques el artículo como completado y reenvíalo con regenerate establecido en true.
Verificación de la firma
La firma es un HMAC-SHA256 (hex) de la cadena articleId|audioFile|srtFile, cifrada con el resumen hex SHA-256 de tu clave API. Vuelve a calcularla de tu lado y compárala para confirmar que el callback proviene de Moknah y no fue manipulado.
import crypto from 'crypto';
const keyHash = crypto.createHash('sha256').update(API_KEY).digest('hex');
const payload = `${articleId}|${audioFile}|${srtFile}`;
const expected = crypto.createHmac('sha256', keyHash).update(payload).digest('hex');
const isValid = expected === signature;
import hashlib, hmac
key_hash = hashlib.sha256(API_KEY.encode()).hexdigest()
payload = f"{article_id}|{audio_file}|{srt_file}"
expected = hmac.new(key_hash.encode(), payload.encode(), hashlib.sha256).hexdigest()
is_valid = hmac.compare_digest(expected, signature)
Idempotencia y regeneración
- Las solicitudes se identifican por articleId por empresa. Un nuevo articleId inicia una nueva generación.
- Si un artículo se está generando actualmente, las solicitudes repetidas se rechazan con 409 ALREADY_PROCESSING.
- Si un artículo ya fue generado y regenerate es false, el audio existente se vuelve a entregar a tu callbackURL sin regenerar (y sin volver a cobrar).
- Establece regenerate en true para forzar una generación completamente nueva para un articleId existente.
- Si un intento anterior para un articleId falló, volver a enviarlo lo genera de nuevo; no necesitas un articleId nuevo.
Concurrencia y rendimiento
Los artículos se generan desde una cola en la que cada cliente recibe una parte justa. Puedes enviar muchos artículos a la vez: todos se aceptan, se generan unos pocos a la vez y cada uno se entrega a tu URL de callback en cuanto está listo.
- Por eso un lote grande se completa de forma gradual y no todo a la vez; no hace falta retener artículos por tu parte.
- Reintenta cualquier artículo fallido con regenerate establecido en true; los artículos ya generados se almacenan en caché y no es necesario reenviarlos.
- El endpoint /process-text también tiene límite de tasa por cliente; las ráfagas por encima del límite reciben 429 Too Many Requests, así que espacia o agrupa tus envíos.
Facturación
El costo en caracteres se calcula multiplicando el número de caracteres en text por el factor de preprocesamiento (1 por defecto, 2 cuando preprocessType es 2). Los créditos solo se descuentan cuando la generación se ejecuta realmente. La reentrega de un artículo ya generado es gratuita y, si falla la generación o la entrega, los créditos descontados se reembolsan automáticamente.
Las voces avanzadas (voice_engine = advanced) se cobran con la tarifa del modo avanzado, además del factor de preprocesamiento.
Errores
| Estado | Código | Descripción |
|---|---|---|
401 |
AUTH_FAILED | Falta el encabezado Authorization o la clave API no es válida. |
422 |
VALIDATION_ERROR | Falta el texto, o faltan campos en postData o no son válidos. |
400 |
INVALID_VOICE_ID | El voiceId proporcionado no existe. |
400 |
UNSUPPORTED_VOICE | La voz no es del tipo de tu clave API (estándar o avanzada) o no está disponible en este momento. |
409 |
ALREADY_PROCESSING | Este artículo ya se está generando. Vuelve a intentarlo cuando termine. |
422 |
PROCESSING_ERROR | La generación falló. Los créditos descontados se reembolsarán. |
422 |
REFUND_FAILED | El procesamiento falló y el reembolso automático no se completó. Contacta a api@moknah.io. |
Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.