Moknah Dokumen
Mulai gratis
Referensi API

Artikel ke Suara (ATS)

Konversikan artikel lengkap menjadi audio narasi dan transkripsi, yang dikirim secara asinkron ke URL callback Anda.

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

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.

Dirancang secara asinkron

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).
Menangani pembuatan yang gagal

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.
Dukungan API

Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.