Artikel naar spraak (ATS)
Zet een volledig artikel om in ingesproken audio en een transcriptie, asynchroon afgeleverd op je callback-URL.
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.
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). |
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. |
Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.