Moknah Dokumentacja
Zacznij za darmo
Dokumentacja API

Zamiana artykułu na mowę (ATS)

Przekształć cały artykuł w nagranie lektorskie oraz transkrypcję, dostarczane asynchronicznie na Twój adres URL zwrotny (callback).

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

Punkt końcowy zamiany artykułu na mowę (ATS) przyjmuje tekst artykułu i generuje nagranie MP3 wraz z zsynchronizowanym plikiem transkrypcji (.srt). Generowanie odbywa się asynchronicznie: żądanie natychmiast zwraca kod 202 Accepted, a gotowe pliki są dostarczane pod wskazany adres callbackURL. Jest to ta sama usługa, która obsługuje wtyczkę ATS dla WordPressa.

Asynchroniczność z założenia

Nie czekaj na plik audio w odpowiedzi HTTP. Punkt końcowy od razu zwraca kod 202 i wysyła wynik żądaniem POST na Twój adres callbackURL po zakończeniu generowania.

Uwierzytelnianie

Dołącz klucz API swojej firmy jako token Bearer w nagłówku Authorization.

Authorization: Bearer your_api_key

Treść żądania

Wyślij treść JSON zawierającą czysty tekst artykułu oraz obiekt postData opisujący żądanie.

Parametr Wymagane Typ Opis
text wymagane string Pełny tekst artykułu do zamiany na mowę.
postData wymagane object Metadane żądania. Zobacz pola poniżej.

Obiekt postData

Pole Wymagane Typ Domyślny Opis
name wymagane string — Tytuł artykułu. Używany jako tytuł wygenerowanego żądania audio.
articleId wymagane string — Twój unikalny identyfikator artykułu. Działa jako klucz idempotentności (zobacz sekcję Idempotentność poniżej) i jest zwracany w wywołaniu zwrotnym.
voiceId wymagane string — Głos używany do narracji. Użyj ID z listy głosów. Używaj głosu zgodnego z typem klucza API Twojej firmy: klucz standardowy korzysta z głosów standardowych (voice_engine = standard), a klucz zaawansowany z głosów zaawansowanych (voice_engine = advanced). Typ wybierasz przy generowaniu klucza. W obu przypadkach każde zdanie w pliku .srt ma znaczniki czasu dla każdego słowa.
callbackURL wymagane string (URL) — Adres URL HTTPS, na który Moknah wyśle żądaniem POST adresy URL gotowego nagrania i transkrypcji. Dla firmy zapisywana jest ostatnia podana wartość.
preprocessType opcjonalne string "0" Tryb przygotowania tekstu: "0" bez obróbki (czytanie dosłowne) lub "2" dla arabskiego taszkilu (AI dodaje znaki samogłoskowe i zapisuje liczby słownie; podwaja koszt za znak). Jako ciąg znaków lub liczba. "2" jest dostępne tylko dla arabskiego, a do AI trafiają wyłącznie zdania po arabsku.
language opcjonalne string "auto" Język treści: "auto" albo kod ISO 639-1, np. "ar" lub "en". Przy "auto" preprocessType "2" jest używany tylko wtedy, gdy tekst jest po arabsku; w przeciwnym razie artykuł jest czytany jak przy "0" i rozliczany jednokrotnie. Wysłanie "2" z językiem innym niż arabski zostanie odrzucone z kodem 422 VALIDATION_ERROR.
regenerate opcjonalne boolean false Gdy ustawione na true, wymusza ponowne wygenerowanie, nawet jeśli ten articleId był już wcześniej generowany.

Przykładowe żądanie

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

Natychmiastowa odpowiedź

Jeśli żądanie zostanie przyjęte, punkt końcowy odpowiada natychmiast:

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

Ładunek wywołania zwrotnego (Callback Payload)

Po zakończeniu generowania Moknah wysyła żądanie POST na Twój adres callbackURL z następującą treścią JSON:

{
    "articleId": "post-123",
    "response": {
        "audioFile": "https://api-storage.moknah.io/.../******.mp3",
        "srtFile": "https://api-storage.moknah.io/.../******.srt",
        "signature": "<hmac-sha256-hex>"
    }
}
Pole Opis
articleId Ten sam identyfikator articleId, który został wysłany w żądaniu.
response.audioFile Publiczny adres URL wygenerowanej narracji MP3 lub null, jeśli generowanie się nie powiodło.
response.srtFile Publiczny adres URL zsynchronizowanego pliku transkrypcji (.srt) lub null, jeśli generowanie się nie powiodło.
response.signature Podpis HMAC-SHA256, którego możesz użyć do zweryfikowania autentyczności ładunku (zobacz poniżej).
Obsługa nieudanych generacji

Wywołanie zwrotne (callback) jest wysyłane również wtedy, gdy generowanie nie utworzy pliku audio. W takim przypadku response.audioFile oraz response.srtFile mają wartość null (podpis nadal obejmuje articleId|null|null). Traktuj każde wywołanie zwrotne, w którym audioFile lub srtFile ma wartość null, jako błąd: nie oznaczaj artykułu jako ukończonego i wyślij go ponownie z parametrem regenerate ustawionym na true.

Weryfikacja podpisu

Podpis to HMAC-SHA256 (hex) ciągu articleId|audioFile|srtFile, utworzony przy użyciu skrótu SHA-256 (hex) Twojego klucza API. Oblicz go ponownie po swojej stronie i porównaj, aby potwierdzić, że wywołanie zwrotne pochodzi z Moknah i nie zostało zmodyfikowane.

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)

Idempotentność i ponowne generowanie

  • Żądania są identyfikowane według articleId dla danej firmy. Nowy articleId rozpoczyna nowe generowanie.
  • Jeśli artykuł jest aktualnie generowany, powtórne żądania są odrzucane z kodem 409 ALREADY_PROCESSING.
  • Jeśli artykuł został już wygenerowany, a parametr regenerate ma wartość false, istniejący plik audio zostanie ponownie dostarczony na Twój adres callbackURL bez ponownego generowania (i bez ponownego naliczania opłat).
  • Ustaw parametr regenerate na true, aby wymusić zupełnie nowe generowanie dla istniejącego articleId.
  • Jeśli poprzednia próba dla danego articleId się nie powiodła, ponowne wysłanie wygeneruje go od nowa; nowy articleId nie jest potrzebny.

Współbieżność i przepustowość

Artykuły są generowane z kolejki, w której każdy klient ma sprawiedliwy udział. Możesz wysłać wiele artykułów naraz: wszystkie zostaną przyjęte, będą generowane po kilka, a każdy trafi na Twój adres callback, gdy tylko będzie gotowy.

  • Duża partia kończy się więc stopniowo, a nie od razu; nie musisz wstrzymywać artykułów po swojej stronie.
  • Ponów próbę dla każdego nieudanego artykułu z parametrem regenerate ustawionym na true; już wygenerowane artykuły są zapisywane w pamięci podręcznej i nie trzeba ich wysyłać ponownie.
  • Punkt końcowy /process-text również podlega limitowi zapytań (rate limit) na klienta; nagłe wzrosty liczby żądań powyżej limitu zwracają błąd 429 Too Many Requests, dlatego rozłóż wysyłanie w czasie lub grupuj żądania w partie.

Rozliczenia

Koszt znaków jest obliczany jako liczba znaków w text pomnożona przez współczynnik wstępnego przetwarzania (domyślnie 1, 2 gdy preprocessType wynosi 2). Kredyty są pobierane tylko wtedy, gdy generowanie faktycznie się uruchomi. Ponowne dostarczenie już wygenerowanego artykułu jest bezpłatne, a w przypadku niepowodzenia generowania lub dostarczenia pobrane kredyty są automatycznie zwracane.

Głosy zaawansowane (voice_engine = advanced) są rozliczane według stawki trybu zaawansowanego, dodatkowo do współczynnika wstępnego przetwarzania.

Błędy

Status Kod Opis
401 AUTH_FAILED Brak nagłówka Authorization lub nieprawidłowy klucz API.
422 VALIDATION_ERROR Brak tekstu lub nieprawidłowe/brakujące pola postData.
400 INVALID_VOICE_ID Podany identyfikator voiceId nie istnieje.
400 UNSUPPORTED_VOICE Ten głos nie pasuje do typu Twojego klucza API (standardowy lub zaawansowany) albo jest teraz niedostępny.
409 ALREADY_PROCESSING Ten artykuł jest już generowany. Spróbuj ponownie po zakończeniu.
422 PROCESSING_ERROR Generowanie nie powiodło się. Pobrane kredyty zostały zwrócone.
422 REFUND_FAILED Przetwarzanie nie powiodło się i automatyczny zwrot nie został ukończony. Skontaktuj się z api@moknah.io.
Wsparcie API

W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.