Moknah Docs
Gratis starten
API-referentie

Artikel naar spraak (ATS)

Zet een volledig artikel om in ingesproken audio en een transcriptie, asynchroon afgeleverd op je callback-URL.

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

Het Artikel-naar-spraak-eindpunt (ATS) accepteert de tekst van een artikel en genereert een MP3-vertelling samen met een gesynchroniseerd transcriptiebestand (.srt). De generatie verloopt asynchroon: het verzoek geeft direct 202 Accepted terug en de voltooide bestanden worden afgeleverd op de door jou opgegeven callbackURL. Dit is dezelfde dienst die de ATS WordPress-plug-in aandrijft.

Asynchroon van opzet

Wacht niet op de HTTP-respons voor je audio. Het eindpunt antwoordt direct met 202 en stuurt het resultaat via POST naar je callbackURL zodra de generatie klaar is.

Authenticatie

Neem je bedrijfs-API-sleutel op als Bearer-token in de Authorization-header.

Authorization: Bearer your_api_key

Request body

Stuur een JSON-body met de onbewerkte artikeltekst en een postData-object dat het verzoek beschrijft.

Parameter Verplicht Type Beschrijving
text verplicht string De volledige tekst van het artikel om naar spraak om te zetten.
postData verplicht object Metadata van het verzoek. Zie de velden hieronder.

postData-object

Veld Verplicht Type Standaard Beschrijving
name verplicht string — Titel van het artikel. Wordt gebruikt als titel van het gegenereerde audioverzoek.
articleId verplicht string — Jouw unieke ID voor het artikel. Fungeert als idempotentie-sleutel (zie Idempotentie hieronder) en wordt teruggestuurd in de callback.
voiceId verplicht string — De stem om mee voor te lezen. Gebruik een ID uit de stemmenlijst. Gebruik een stem van het type van de API-sleutel van uw bedrijf: een standaardsleutel gebruikt standaardstemmen (voice_engine = standard), een geavanceerde sleutel geavanceerde stemmen (voice_engine = advanced). U kiest het type bij het genereren van de sleutel. In beide gevallen heeft elke zin in het .srt-bestand tijden per woord.
callbackURL verplicht string (URL) — HTTPS-URL waarnaar Moknah de voltooide audio- en transcriptie-URL's via POST stuurt. De nieuwste waarde wordt opgeslagen voor het bedrijf.
preprocessType optioneel string "0" Tekstvoorbereidingsmodus: "0" voor geen (letterlijk voorlezen) of "2" voor Arabische tashkeel (de AI voegt klinkertekens toe en schrijft getallen voluit; verdubbelt de tekenkosten). Als string of als getal. "2" is alleen beschikbaar voor Arabisch, en alleen Arabische zinnen worden naar de AI gestuurd.
language optioneel string "auto" Taal van de inhoud: "auto" of een ISO 639-1-code zoals "ar" of "en". Met "auto" wordt preprocessType "2" alleen gebruikt als de tekst Arabisch is; anders wordt het artikel voorgelezen als "0" en één keer in rekening gebracht. "2" met een andere taal dan Arabisch wordt geweigerd met 422 VALIDATION_ERROR.
regenerate optioneel boolean false Wanneer ingesteld op true, wordt een nieuwe generatie geforceerd, zelfs als dit articleId al eerder is gegenereerd.

Voorbeeldverzoek

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

Directe respons

Als het verzoek wordt geaccepteerd, reageert het eindpunt direct:

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

Callback-payload

Wanneer de generatie klaar is, stuurt Moknah een POST-verzoek naar je callbackURL met deze JSON-body:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}
Veld Beschrijving
articleId Hetzelfde articleId dat je in het verzoek hebt meegestuurd.
response.audioFile Openbare URL van de gegenereerde MP3-narratie, of null als het genereren is mislukt.
response.srtFile Openbare URL van het gesynchroniseerde transcriptiebestand (.srt), of null als het genereren is mislukt.
response.signature HMAC-SHA256-handtekening waarmee je kunt verifiëren dat de payload authentiek is (zie hieronder).
Mislukte generaties afhandelen

Er wordt ook een callback verzonden wanneer het genereren geen audio oplevert. In dat geval zijn response.audioFile en response.srtFile null (de handtekening dekt nog steeds articleId|null|null). Behandel elke callback waarvan audioFile of srtFile null is als een fout: markeer het artikel niet als voltooid en verzend het opnieuw met regenerate ingesteld op true.

De handtekening verifiëren

De handtekening is een HMAC-SHA256 (hex) van de tekenreeks articleId|audioFile|srtFile, versleuteld met de SHA-256-hexdigest van je API-sleutel. Bereken deze aan jouw kant opnieuw en vergelijk om te bevestigen dat de callback afkomstig is van Moknah en niet is gemanipuleerd.

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)

Idempotentie & opnieuw genereren

  • Verzoeken worden per bedrijf gekoppeld aan een articleId. Een nieuwe articleId start een nieuwe generatie.
  • Als een artikel momenteel wordt gegenereerd, worden herhaalde verzoeken geweigerd met 409 ALREADY_PROCESSING.
  • Als een artikel al is gegenereerd en regenerate op false staat, wordt de bestaande audio opnieuw afgeleverd op je callbackURL zonder opnieuw te genereren (en zonder extra kosten).
  • Stel regenerate in op true om een volledig nieuwe generatie voor een bestaande articleId af te dwingen.
  • Is een eerdere poging voor een articleId mislukt, dan wordt het bij opnieuw verzenden opnieuw gemaakt; een nieuwe articleId is niet nodig.

Gelijktijdigheid & doorvoer

Artikelen worden gemaakt vanuit een wachtrij waarin elke klant een eerlijk deel krijgt. U kunt veel artikelen tegelijk insturen: ze worden allemaal geaccepteerd, een paar tegelijk gemaakt, en elk artikel wordt bij uw callback-URL afgeleverd zodra het klaar is.

  • Een grote batch wordt dus geleidelijk voltooid en niet in één keer; u hoeft geen artikelen achter te houden.
  • Probeer elk mislukt artikel opnieuw met regenerate ingesteld op true; reeds gegenereerde artikelen worden gecachet en hoeven niet opnieuw te worden verzonden.
  • Het /process-text-endpoint heeft ook een rate-limit per client; pieken boven de limiet krijgen 429 Too Many Requests, dus spreid je verzoeken of verzend ze in batches.

Facturering

De tekenkosten worden berekend als het aantal tekens in text vermenigvuldigd met de voorbewerkingsfactor (standaard 1, 2 wanneer preprocessType gelijk is aan 2). Credits worden alleen afgeschreven wanneer de generatie daadwerkelijk wordt uitgevoerd. Het opnieuw leveren van een al gegenereerd artikel is gratis, en als de generatie of levering mislukt, worden de afgeschreven credits automatisch teruggestort.

Geavanceerde stemmen (voice_engine = advanced) worden berekend tegen het tarief van de geavanceerde modus, bovenop de voorbewerkingsfactor.

Fouten

Status Code Beschrijving
401 AUTH_FAILED Ontbrekende Authorization-header of ongeldige API-sleutel.
422 VALIDATION_ERROR Ontbrekende tekst of ongeldige/ontbrekende postData-velden.
400 INVALID_VOICE_ID De opgegeven voiceId bestaat niet.
400 UNSUPPORTED_VOICE De stem hoort niet bij het type van uw API-sleutel (standaard of geavanceerd) of is nu niet beschikbaar.
409 ALREADY_PROCESSING Dit artikel wordt al gegenereerd. Probeer het opnieuw zodra dit is voltooid.
422 PROCESSING_ERROR Generatie mislukt. Afgeschreven credits worden teruggestort.
422 REFUND_FAILED De verwerking is mislukt en de automatische terugbetaling is niet voltooid. Neem contact op met api@moknah.io.
API-ondersteuning

Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.