Artikel ke Suara (ATS)
Konversikan artikel lengkap menjadi audio narasi dan transkripsi, yang dikirim secara asinkron ke URL callback Anda.
Endpoint Artikel ke Suara (ATS) menerima teks artikel dan menghasilkan narasi MP3 beserta file transkripsi yang disinkronkan (.srt). Pembuatan berjalan secara asinkron: permintaan langsung mengembalikan 202 Accepted, dan file yang telah selesai dikirimkan ke callbackURL yang Anda berikan. Ini adalah layanan yang sama yang mendukung plugin WordPress ATS.
Jangan menunggu audio Anda pada respons HTTP. Endpoint langsung membalas dengan kode 202 dan mengirimkan hasilnya melalui POST ke callbackURL Anda saat pembuatan selesai.
Autentikasi
Sertakan kunci API perusahaan Anda sebagai token Bearer di header Authorization.
Authorization: Bearer your_api_key
Isi Permintaan (Request Body)
Kirim body JSON berisi teks artikel mentah dan objek postData yang menjelaskan permintaan tersebut.
| Parameter | Wajib | Jenis | Deskripsi |
|---|---|---|---|
| text | wajib | string | Teks artikel lengkap yang akan dikonversi menjadi suara. |
| postData | wajib | object | Metadata permintaan. Lihat kolom di bawah ini. |
Objek postData
| Kolom | Wajib | Jenis | Default | Deskripsi |
|---|---|---|---|---|
| name | wajib | string | — | Judul artikel. Digunakan sebagai judul permintaan audio yang dihasilkan. |
| articleId | wajib | string | — | Pengidentifikasi unik Anda untuk artikel tersebut. Berfungsi sebagai kunci idempotensi (lihat Idempotensi di bawah) dan dikirimkan kembali dalam callback. |
| voiceId | wajib | string | — | Suara yang digunakan untuk narasi. Gunakan ID dari daftar suara. Gunakan suara sesuai jenis kunci API perusahaan Anda: kunci standar memakai suara standar (voice_engine = standard), kunci lanjutan memakai suara lanjutan (voice_engine = advanced). Jenisnya Anda pilih saat membuat kunci. Dalam kedua kasus, setiap kalimat di file .srt memiliki waktu per kata. |
| callbackURL | wajib | string (URL) | — | URL HTTPS tujuan Moknah mengirimkan URL audio dan transkripsi yang telah selesai melalui POST. Nilai terbaru disimpan untuk perusahaan. |
| preprocessType | opsional | string | "0" | Mode persiapan teks: "0" untuk tanpa persiapan (narasikan apa adanya) atau "2" untuk tashkeel Arab (AI menambahkan harakat dan menuliskan angka sebagai kata; menggandakan biaya per karakter). Dapat berupa string atau angka. "2" hanya tersedia untuk bahasa Arab, dan hanya kalimat berbahasa Arab yang dikirim ke AI. |
| language | opsional | string | "auto" | Bahasa konten: "auto" atau kode ISO 639-1 seperti "ar" atau "en". Dengan "auto", preprocessType "2" hanya dipakai jika teksnya berbahasa Arab; jika tidak, artikel dinarasikan seperti "0" dan ditagih sekali. Mengirim "2" dengan bahasa selain Arab ditolak dengan 422 VALIDATION_ERROR. |
| regenerate | opsional | boolean | false | Jika bernilai true, memaksa pembuatan ulang meskipun articleId ini sudah pernah dibuat sebelumnya. |
Contoh Permintaan
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
Respons Langsung
Jika permintaan diterima, endpoint langsung merespons:
Processing started. Results will be sent to the callback URL.
Payload Callback
Saat pembuatan selesai, Moknah mengirimkan permintaan POST ke callbackURL Anda dengan body JSON berikut:
{
"articleId": "post-123",
"response": {
"audioFile": "https://api-storage.moknah.io/.../******.mp3",
"srtFile": "https://api-storage.moknah.io/.../******.srt",
"signature": "<hmac-sha256-hex>"
}
}
| Kolom | Deskripsi |
|---|---|
| articleId | articleId yang sama dengan yang Anda kirimkan dalam permintaan. |
| response.audioFile | URL publik dari narasi MP3 yang dihasilkan, atau null jika pembuatan gagal. |
| response.srtFile | URL publik dari file transkripsi tersinkronisasi (.srt), atau null jika pembuatan gagal. |
| response.signature | Tanda tangan HMAC-SHA256 yang dapat Anda gunakan untuk memverifikasi keaslian payload (lihat di bawah). |
Callback juga dikirim saat pembuatan tidak menghasilkan audio. Dalam kasus tersebut, response.audioFile dan response.srtFile bernilai null (tanda tangan tetap mencakup articleId|null|null). Perlakukan setiap callback yang audioFile atau srtFile-nya bernilai null sebagai kegagalan: jangan tandai artikel sebagai selesai, dan kirim ulang dengan regenerate diatur ke true.
Memverifikasi Tanda Tangan
Tanda tangan tersebut adalah HMAC-SHA256 (hex) dari string articleId|audioFile|srtFile, dengan kunci digest hex SHA-256 dari kunci API Anda. Hitung ulang di sisi Anda dan bandingkan untuk memastikan callback berasal dari Moknah dan tidak dimanipulasi.
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)
Idempotensi & Regenerasi
- Permintaan diidentifikasi berdasarkan articleId per perusahaan. articleId baru akan memulai pembuatan baru.
- Jika artikel sedang dibuat, permintaan berulang akan ditolak dengan kode 409 ALREADY_PROCESSING.
- Jika artikel sudah pernah dibuat dan regenerate bernilai false, audio yang ada akan dikirim ulang ke callbackURL Anda tanpa dibuat ulang (dan tanpa dikenakan biaya lagi).
- Atur regenerate ke true untuk memaksa pembuatan baru untuk articleId yang sudah ada.
- Jika percobaan sebelumnya untuk suatu articleId gagal, mengirimkannya lagi akan membuatnya ulang; Anda tidak perlu articleId baru.
Konkurensi & throughput
Artikel dibuat dari antrean yang memberi setiap klien bagian yang adil. Anda dapat mengirim banyak artikel sekaligus: semuanya diterima, dibuat beberapa sekaligus, dan masing-masing dikirim ke URL callback Anda begitu siap.
- Karena itu batch besar selesai secara bertahap, tidak sekaligus; Anda tidak perlu menahan artikel di sisi Anda.
- Coba lagi artikel yang gagal dengan mengatur regenerate ke true; artikel yang sudah dibuat telah disimpan di cache dan tidak perlu dikirim ulang.
- Endpoint /process-text juga memiliki batas laju (rate-limit) per klien; lonjakan permintaan yang melebihi batas akan menerima 429 Too Many Requests, jadi beri jeda atau kirimkan permintaan Anda secara bertahap (batch).
Penagihan
Biaya karakter dihitung dari jumlah karakter dalam text dikalikan dengan faktor prapemrosesan (default 1, 2 jika preprocessType bernilai 2). Kredit hanya dipotong saat pembuatan benar-benar dijalankan. Pengiriman ulang artikel yang sudah dibuat tidak dikenakan biaya, dan jika pembuatan atau pengiriman gagal, kredit yang telah dipotong akan dikembalikan secara otomatis.
Suara lanjutan (voice_engine = advanced) dikenakan tarif mode lanjutan, di samping faktor prapemrosesan.
Error
| Status | Kode | Deskripsi |
|---|---|---|
401 |
AUTH_FAILED | Header Authorization tidak ada atau kunci API tidak valid. |
422 |
VALIDATION_ERROR | Teks tidak ada, atau kolom postData tidak valid/tidak ada. |
400 |
INVALID_VOICE_ID | voiceId yang diberikan tidak ada. |
400 |
UNSUPPORTED_VOICE | Suara ini bukan jenis kunci API Anda (standar atau lanjutan), atau sedang tidak tersedia. |
409 |
ALREADY_PROCESSING | Artikel ini sedang dibuat. Coba lagi setelah selesai. |
422 |
PROCESSING_ERROR | Pembuatan gagal. Kredit yang telah dipotong akan dikembalikan. |
422 |
REFUND_FAILED | Pemrosesan gagal dan pengembalian dana otomatis tidak selesai. Hubungi api@moknah.io. |
Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.