Moknah Documentación
Empieza gratis
Referencia de la API

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.

POST https://api.moknah.io/process-text

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.

Asíncrono por diseño

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).
Manejar generaciones fallidas

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.
Soporte de API

Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.