Moknah Doku
Kostenlos starten
API-Referenz

Artikel zu Sprache (ATS)

Wandeln Sie einen vollständigen Artikel in vertontes Audio und eine Transkription um, die asynchron an Ihre Callback-URL geliefert werden.

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

Der Artikel-zu-Sprache-Endpunkt (ATS) nimmt den Text eines Artikels entgegen und erstellt eine MP3-Sprachausgabe zusammen mit einer synchronisierten Transkriptionsdatei (.srt). Die Generierung erfolgt asynchron: Die Anfrage gibt sofort 202 Accepted zurück, und die fertigen Dateien werden an die von Ihnen angegebene callbackURL gesendet. Dies ist derselbe Dienst, der auch das ATS-WordPress-Plugin antreibt.

Grundlegend asynchron

Warten Sie in der HTTP-Antwort nicht auf Ihr Audio. Der Endpunkt antwortet sofort mit 202 und sendet das Ergebnis per POST an Ihre callbackURL, sobald die Generierung abgeschlossen ist.

Authentifizierung

Fügen Sie Ihren Unternehmens-API-Schlüssel als Bearer-Token im Authorization-Header hinzu.

Authorization: Bearer your_api_key

Anfragekörper (Request Body)

Senden Sie einen JSON-Body mit dem reinen Artikeltext und einem postData-Objekt, das die Anfrage beschreibt.

Parameter Erforderlich Typ Beschreibung
text erforderlich string Der vollständige Artikeltext, der in Sprache umgewandelt werden soll.
postData erforderlich object Metadaten der Anfrage. Siehe die Felder unten.

postData-Objekt

Feld Erforderlich Typ Standard Beschreibung
name erforderlich string — Titel des Artikels. Wird als Titel der generierten Audioanfrage verwendet.
articleId erforderlich string — Ihre eindeutige Kennung für den Artikel. Dient als Idempotenzschlüssel (siehe Idempotenz unten) und wird im Callback zurückgegeben.
voiceId erforderlich string — Die Stimme für die Sprachausgabe. Verwenden Sie eine ID aus der Stimmenliste. Verwenden Sie eine Stimme vom Typ Ihres Firmen-API-Schlüssels: Ein Standard-Schlüssel nutzt Standard-Stimmen (voice_engine = standard), ein erweiterter Schlüssel erweiterte Stimmen (voice_engine = advanced). Den Typ wählen Sie beim Erzeugen des Schlüssels. In beiden Fällen ist jeder Satz in der .srt-Datei wortgenau getaktet.
callbackURL erforderlich string (URL) — HTTPS-URL, an die Moknah die fertigen Audio- und Transkriptions-URLs per POST sendet. Der jeweils neueste Wert wird für das Unternehmen gespeichert.
preprocessType optional string "0" Textvorbereitungsmodus: "0" für keine Bearbeitung (wörtliche Sprachausgabe) oder "2" für arabisches Taschkīl (die KI setzt Vokalzeichen und schreibt Zahlen aus; verdoppelt die Zeichenkosten). Als String oder Zahl. "2" ist nur für Arabisch verfügbar, und nur arabische Sätze werden an die KI gesendet.
language optional string "auto" Inhaltssprache: "auto" oder ein ISO-639-1-Code wie "ar" oder "en". Mit "auto" wird preprocessType "2" nur verwendet, wenn der Text arabisch ist; andernfalls wird der Artikel wie mit "0" vorgelesen und einfach berechnet. "2" zusammen mit einer anderen Sprache als Arabisch wird mit 422 VALIDATION_ERROR abgelehnt.
regenerate optional boolean false Wenn true, wird eine neue Generierung erzwungen, selbst wenn diese articleId bereits zuvor generiert wurde.

Beispielanfrage

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

Sofortige Antwort

Wenn die Anfrage akzeptiert wird, antwortet der Endpunkt sofort:

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

Callback-Nutzdaten (Payload)

Sobald die Generierung abgeschlossen ist, sendet Moknah eine POST-Anfrage mit diesem JSON-Body an Ihre callbackURL:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}
Feld Beschreibung
articleId Dieselbe articleId, die Sie in der Anfrage gesendet haben.
response.audioFile Öffentliche URL der generierten MP3-Sprachausgabe oder null, falls die Generierung fehlgeschlagen ist.
response.srtFile Öffentliche URL der synchronisierten Transkriptionsdatei (.srt) oder null, falls die Generierung fehlgeschlagen ist.
response.signature HMAC-SHA256-Signatur, mit der Sie die Authentizität der Payload überprüfen können (siehe unten).
Fehlgeschlagene Generierungen behandeln

Ein Callback wird auch gesendet, wenn die Generierung kein Audio erzeugt. In diesem Fall sind response.audioFile und response.srtFile null (die Signatur deckt weiterhin articleId|null|null ab). Behandeln Sie jeden Callback, bei dem audioFile oder srtFile null ist, als Fehler: Markieren Sie den Artikel nicht als abgeschlossen und senden Sie ihn erneut mit regenerate auf true gesetzt.

Überprüfen der Signatur

Die Signatur ist ein HMAC-SHA256 (Hex) der Zeichenfolge articleId|audioFile|srtFile, verschlüsselt mit dem SHA-256-Hex-Digest Ihres API-Schlüssels. Berechnen Sie sie auf Ihrer Seite neu und vergleichen Sie sie, um sicherzustellen, dass der Callback von Moknah stammt und nicht manipuliert wurde.

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)

Idempotenz & Neugenerierung

  • Anfragen werden pro Unternehmen über die articleId zugeordnet. Eine neue articleId startet eine neue Generierung.
  • Wenn ein Artikel gerade generiert wird, werden wiederholte Anfragen mit 409 ALREADY_PROCESSING abgelehnt.
  • Wenn ein Artikel bereits generiert wurde und regenerate auf false steht, wird das vorhandene Audio erneut an Ihre callbackURL geliefert, ohne es neu zu generieren (und ohne erneute Berechnung).
  • Setzen Sie regenerate auf true, um eine komplett neue Generierung für eine bestehende articleId zu erzwingen.
  • Ist ein früherer Versuch für eine articleId fehlgeschlagen, wird sie beim erneuten Senden neu erzeugt; eine neue articleId ist nicht nötig.

Gleichzeitigkeit & Durchsatz

Artikel werden aus einer Warteschlange erzeugt, in der jeder Kunde einen fairen Anteil erhält. Sie können viele Artikel auf einmal senden: Alle werden angenommen, einige gleichzeitig erzeugt, und jeder wird an Ihre Callback-URL geliefert, sobald er fertig ist.

  • Ein großer Stapel wird daher nach und nach fertig statt auf einmal; Sie müssen keine Artikel zurückhalten.
  • Wiederholen Sie fehlgeschlagene Artikel mit regenerate auf true gesetzt; bereits generierte Artikel werden zwischengespeichert und müssen nicht erneut gesendet werden.
  • Der Endpunkt /process-text unterliegt ebenfalls einem Rate-Limit pro Client; Anfragespitzen über dem Limit erhalten 429 Too Many Requests, verteilen Sie Ihre Anfragen daher zeitlich oder bündeln Sie sie.

Abrechnung

Die Zeichenkosten berechnen sich aus der Anzahl der Zeichen in text multipliziert mit dem Vorverarbeitungsfaktor (standardmäßig 1, 2 wenn preprocessType gleich 2 ist). Credits werden nur abgezogen, wenn die Generierung tatsächlich ausgeführt wird. Die erneute Zustellung eines bereits generierten Artikels ist kostenlos, und falls die Generierung oder Zustellung fehlschlägt, werden die abgezogenen Credits automatisch zurückerstattet.

Erweiterte Stimmen (voice_engine = advanced) werden zum Tarif des erweiterten Modus berechnet, zusätzlich zum Vorverarbeitungsfaktor.

Fehler

Status Code Beschreibung
401 AUTH_FAILED Authorization-Header fehlt oder ungültiger API-Schlüssel.
422 VALIDATION_ERROR Text fehlt oder ungültige/fehlende postData-Felder.
400 INVALID_VOICE_ID Die angegebene voiceId existiert nicht.
400 UNSUPPORTED_VOICE Die Stimme passt nicht zum Typ Ihres API-Schlüssels (Standard oder erweitert) oder ist gerade nicht verfügbar.
409 ALREADY_PROCESSING Dieser Artikel wird bereits generiert. Versuchen Sie es erneut, sobald der Vorgang abgeschlossen ist.
422 PROCESSING_ERROR Generierung fehlgeschlagen. Abgezogene Credits werden zurückerstattet.
422 REFUND_FAILED Die Verarbeitung ist fehlgeschlagen und die automatische Rückerstattung wurde nicht abgeschlossen. Kontaktieren Sie api@moknah.io.
API-Support

Bei Fragen oder Problemen rund um die API kontaktieren Sie uns unter api@moknah.io.