Zamiana artykułu na mowę (ATS)
Przekształć cały artykuł w nagranie lektorskie oraz transkrypcję, dostarczane asynchronicznie na Twój adres URL zwrotny (callback).
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.
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). |
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. |
W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.