Article to Speech (ATS)

Convert a full article into narrated audio and a transcription, delivered asynchronously to your callback URL.

The Article to Speech (ATS) endpoint accepts the text of an article and generates an MP3 narration together with a synchronized transcription (.srt) file. Generation runs asynchronously: the request returns immediately with 202 Accepted, and the finished files are delivered to the callbackURL you provide. This is the same service that powers the ATS WordPress plugin.

Authentication

Include your company API key as a Bearer token in the Authorization header.

Authorization: Bearer your_api_key

Request Body

Send a JSON body with the raw article text and a postData object describing the request.

postData Object

Example Request

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",
        "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",
            "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',
                regenerate: false
            }
        })
    }
);

// 202 Accepted — result arrives at your callbackURL

Immediate Response

If the request is accepted, the endpoint responds immediately:

Processing started. Results will be sent to the callback URL.

Callback Payload

When generation finishes, Moknah sends a POST request to your callbackURL with this JSON body:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}

Verifying the Signature

The signature is an HMAC-SHA256 (hex) of the string articleId|audioFile|srtFile, keyed with the SHA-256 hex digest of your API key. Recompute it on your side and compare to confirm the callback came from Moknah and was not tampered with.

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)

Idempotency & Regeneration

• Requests are keyed by articleId per company. A new articleId starts a fresh generation.
• If an article is currently being generated, repeat requests are rejected with 409 ALREADY_PROCESSING.
• If an article was already generated and regenerate is false, the existing audio is re-delivered to your callbackURL without re-generating (and without re-charging).
• Set regenerate to true to force a brand-new generation for an existing articleId.
• If a previous attempt failed, the stored result for that articleId may be empty. A later request with regenerate false can then re-deliver that empty result, so resend with regenerate true (or use a new articleId) to recover.

Concurrency & throughput

Each article is narrated by generating its sentences in parallel against the upstream text-to-speech provider, which enforces a concurrency limit shared across your whole account. Submitting many articles at the same time can exceed that limit and cause individual sentences — and therefore whole articles — to fail.

• When narrating a multi-part page, keep only a few articles in flight at once (around three) instead of submitting them all simultaneously.
• Retry any failed article with regenerate set to true; already-generated articles are cached and need not be resent.
• The /process-text endpoint is also rate-limited per client; bursts above the limit receive 429 Too Many Requests, so space out or batch your submissions.

Billing

Character cost is calculated as the number of characters in text multiplied by the preprocessing factor (1 by default, 2 when preprocessType is 2). Credits are deducted only when generation actually runs. Re-delivery of an already-generated article is free, and if generation or delivery fails the deducted credits are refunded automatically.

Errors