Teks ke Suara (TTS)
Ubah teks menjadi suara yang terdengar alami
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 |
Untuk pertanyaan atau masalah terkait API, hubungi kami di api@moknah.io.