Moknah Dokumen
Mulai gratis
Referensi API

Teks ke Suara (TTS)

Ubah teks menjadi suara yang terdengar alami

POST /api/v1/tts/generate/

Ubah teks menjadi suara menggunakan sintesis suara AI. Mengembalikan file audio MP3.

Autentikasi

Sertakan kunci API Anda di header Authorization.

Isi Permintaan (Request Body)

Parameter Wajib Jenis Deskripsi
text wajib string Teks yang akan dikonversi (maks. 1500 karakter)
output_format opsional string Format output audio yang diinginkan. Ditentukan sebagai codec_sampleRate_bitrate (mis., mp3_22050_32). Default-nya adalah mp3_44100_128. Lihat bagian Format Output di bawah untuk daftar lengkapnya.
voice_id wajib integer ID Suara dari daftar suara.
prerecording opsional integer 1 (Peningkatan Dasar), 2 (Peningkatan AI / Tashkeel Arab), atau 3 (Penyair AI). 2 dan 3 hanya tersedia untuk konten berbahasa Arab; lihat language.
language opsional string Bahasa konten sebagai kode ISO 639-1, misalnya ar atau en (kode wilayah seperti ar-JO diterima). Parameter ini menentukan mode prarekaman mana yang diizinkan dan tidak dikirim ke suara. Mode 2 dan 3 hanya tersedia untuk bahasa Arab (ar). Jika language dikosongkan, 2 dan 3 otomatis mengasumsikan bahasa Arab, sehingga integrasi yang ada tetap berfungsi. Bahasa lain dengan mode 2 atau 3, atau kode yang tidak dikenal, akan mengembalikan 400 INVALID_REQUEST dengan alasan di bawah details.language.
voice_settings opsional string (JSON) Opsi kustomisasi suara

Format Output yang Didukung

Parameter output_format dapat berisi salah satu nilai berikut:

  • MP3: mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192
  • PCM: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000
  • Opus: opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192
  • WAV: wav_16000, wav_22050, wav_24000, wav_44100, wav_48000 — WAV mono 16-bit dari output asli mesin (lossless). Tidak tersedia di WebSocket streaming; gunakan pcm_* di sana.

Bagian ini berfungsi sebagai referensi, sehingga pengguna dapat memilih format yang sesuai tanpa memenuhi tabel permintaan utama.

Mesin & Mode

Setiap suara termasuk dalam salah satu dari dua mesin. Daftar suara mengembalikannya sebagai voice_engine, dan suara yang Anda pilih menentukan pengaturan mana yang berlaku.

Setiap kunci API untuk satu mesin: standar (bawaan) atau lanjutan, dipilih saat membuat kunci. Kunci hanya menampilkan dan memakai suara dari mesinnya; buat kunci kedua untuk memakai mesin lainnya.

  • Mesin Standar (standard) — suara studio dengan tiga mode yang menyeimbangkan kecepatan, ekspresivitas, dan harga.
  • Mesin Tingkat Lanjut (advanced, alfa) — suaranya sendiri, diarahkan dalam bahasa alami dengan context, setting, style, dan pace. Mode tidak berlaku.

Mode mesin Standar

mode Nama Kredit Cocok untuk
emotion default Emosi & dialek ×1 Suara cepat dan ekspresif dengan emosi serta dialek. Mendukung tag emosi seperti [laughing] dan [whispering].
quality Emosi & dialek berkualitas ×2 Emosi dan dialek yang lebih kaya serta alami. Membutuhkan waktu sedikit lebih lama. Mendukung tag emosi.
studio Kualitas Studio ×2 Narasi studio yang jernih dan konsisten dengan kontrol suara penuh. Tanpa tag emosi.

Permintaan tanpa mode dijalankan dalam mode emotion.

Objek Pengaturan Suara

Suara mesin Standar

Parameter Jenis Rentang Default Deskripsi
mode string emotion, quality, studio emotion Mode mesin Standar. quality dan studio membutuhkan ×2 kredit. Lihat Mesin & Mode di atas.
temperature integer 0 – 100 25 Mengontrol variabilitas dan ekspresivitas ucapan. Nilai yang lebih rendah menghasilkan ucapan yang lebih stabil dan terprediksi, sedangkan nilai yang lebih tinggi meningkatkan variasi, spontanitas, dan penyampaian yang kreatif.
voice_similarity integer 0 – 100 100 Menentukan seberapa mirip ucapan yang dihasilkan dengan profil suara yang dipilih. Nilai yang lebih tinggi mempertahankan identitas suara asli, sedangkan nilai yang lebih rendah memungkinkan lebih banyak variasi dalam nada dan artikulasi.
speed float 0.7 – 1.2 1.0 Menyesuaikan kecepatan bicara. Nilai di bawah 1.0 memperlambat ucapan agar lebih jelas, sedangkan nilai di atas 1.0 mempercepat ucapan. Khusus mode studio; diabaikan dalam emotion dan quality.
enable_emotions usang boolean false / true — Masih diterima untuk kompatibilitas tetapi tidak lagi mengubah output. Gunakan mode sebagai gantinya.
fast_mode usang integer 0, 1, or 2 — Masih diterima untuk kompatibilitas tetapi tidak lagi mengubah output; mode emotion sudah menjadi opsi cepat. Untuk audio real-time, gunakan endpoint streaming.

Dalam mode emotion dan quality, temperature dan voice_similarity adalah kontrol suara (nilai apa pun dalam rentang digunakan apa adanya); speed hanya berlaku untuk mode studio.

Suara mesin Lanjutan

Parameter Jenis Nilai Deskripsi
context string hingga 500 karakter Kontrol paling kuat. Jelaskan aksen, perasaan, suasana, atau tujuan, mis. “Narasi dokumenter yang hangat dalam dialek Levantin.”
setting string hingga 500 karakter Suasana dan mood, mis. “Studio larut malam yang tenang dan intim.”
style string neutral, warm, energetic, serious, cheerful, poetic Gaya penyampaian secara keseluruhan.
pace string slow, normal, fast Tempo bicara.

Suara mesin Lanjutan mengabaikan mode dan penggeser mesin Standar, serta mengembalikan output_format yang diminta. Pembuatan mungkin memakan waktu sedikit lebih lama daripada mesin Standar.

Aturan & Batasan Pengaturan Suara

  • Kunci yang tidak dikenal, mode, style, atau pace yang tidak valid, atau context/setting yang lebih dari 500 karakter akan ditolak dengan 400 INVALID_REQUEST.
  • Untuk kompatibilitas, saat enable_emotions yang usang bernilai true, kolom berikut tidak boleh disertakan dalam voice_settings: speed, fast_mode.

Harga

Kredit = karakter × (tarif prarekaman + biaya suara %) × pengali mode. Pengalinya adalah ×2 untuk quality dan studio, ×1 untuk emotion, dan ×1.5 untuk setiap suara mesin Lanjutan.

Contoh

curl -X POST "https://moknah.io/api/v1/tts/generate/" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحبا بك في منصة مكنة",
    "voice_id": 1,
    "prerecording": 1,
    "language": "ar",
    "voice_settings": {
        "mode": "emotion",
        "speed": 1.0,
        "temperature": 25
    }
  }' \
  --output speech.mp3

# Advanced engine voice (voice_engine = "advanced")
curl -X POST "https://moknah.io/api/v1/tts/generate/" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "مرحبا بك في منصة مكنة",
    "voice_id": 2,
    "voice_settings": {
        "context": "A warm documentary read in a Levantine dialect.",
        "pace": "slow"
    }
  }' \
  --output speech-advanced.mp3
import requests

response = requests.post(
    "https://moknah.io/api/v1/tts/generate/",
    headers={
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "text": "مرحبا بك في منصة مكنة",
        "voice_id": 1,
        "prerecording": 1,
        "language": "ar",
        "voice_settings": {
            "mode": "emotion",
            "speed": 1.0,
            "temperature": 25
        }
    }
)

with open("speech.mp3", "wb") as f:
    f.write(response.content)
const response = await fetch(
    'https://moknah.io/api/v1/tts/generate/',
    {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_api_key',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            text: 'مرحبا بك في منصة مكنة',
            voice_id: 1,
            prerecording: 1,
            language: 'ar',
            voice_settings: {
                mode: 'emotion',
                speed: 1.0,
                temperature: 25
            }
        })
    }
);

const blob = await response.blob();
// Save or play the audio

Respons

Mengembalikan data audio biner dalam output_format yang diminta (default MP3) dengan header berikut:

Header Deskripsi
Content-Type Sesuai dengan output_format: audio/mpeg untuk mp3_*, audio/ogg untuk opus_* (Ogg/Opus), audio/pcm;rate=N;channels=1 untuk pcm_* (raw 16-bit little-endian, tanpa header).

Error

Status Kode Deskripsi
400 INVALID_REQUEST Parameter tidak valid (termasuk mode, style, atau pace yang tidak dikenal)
401 UNAUTHORIZED Kunci API tidak valid
402 INSUFFICIENT_CREDITS Kredit tidak mencukupi
429 RATE_LIMIT_EXCEEDED Terlalu banyak permintaan
Dukungan API

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