Text to Speech (TTS)
Convert text to natural-sounding speech
Convert text to speech using AI voice synthesis. Returns an MP3 audio file.
Authentication
Include your API key in the Authorization header.
Request Body
| Parameter | Required | Type | Description |
|---|---|---|---|
| text | required | string | Text to convert (max 1500 characters) |
| output_format | optional | string | Desired audio output format. Specified as codec_sampleRate_bitrate (e.g., mp3_22050_32). Default is mp3_44100_128. See Output Formats section below for the full list. |
| voice_id | required | integer | Voice ID from the voice list. |
| prerecording | optional | integer | 1 (Basic Enhancement), 2 (AI Enhancement / Arabic Tashkeel) or 3 (AI Poet). 2 and 3 are available only for Arabic content; see language. |
| language | optional | string | Content language as an ISO 639-1 code, for example ar or en (region codes such as ar-JO are accepted). It decides which prerecording modes are allowed and is not sent to the voice. Modes 2 and 3 are available only for Arabic (ar). If language is omitted, 2 and 3 imply Arabic, so existing integrations keep working. Any other language with 2 or 3, or an unknown code, returns 400 INVALID_REQUEST with the reason under details.language. |
| voice_settings | optional | string (JSON) | Voice customization options |
Supported Output Formats
The output_format parameter can be any of the following values:
- 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 — 16-bit mono WAV of the engine's own output (lossless). Not available on the streaming WebSocket; use pcm_* there.
This section serves as a reference, so users can select the appropriate format without cluttering the main request table.
Engines & Modes
Every voice belongs to one of two engines. The voice list returns it as voice_engine, and the voice you pick decides which settings apply.
Each API key is for one engine: Standard (the default) or Advanced, chosen when you create the key. A key lists and uses only the voices of its engine; create a second key to use the other one.
- Standard engine (
standard) — studio voices with three modes that trade speed, expressiveness and price. - Advanced engine (
advanced, alpha) — its own voices, directed in plain language with context, setting, style and pace. Modes do not apply.
Standard engine modes
| mode | Name | Credits | Best for |
|---|---|---|---|
emotion default |
Emotion & dialect | ×1 | Fast, expressive speech with emotions and dialects. Supports emotion tags such as [laughing] and [whispering]. |
quality |
Quality emotion & dialect | ×2 | Richer, more natural emotions and dialects. Takes a little longer. Supports emotion tags. |
studio |
Studio Quality | ×2 | Clean, consistent studio narration with full voice controls. No emotion tags. |
Requests without a mode run in emotion mode.
Voice Settings Object
Standard engine voices
| Parameter | Type | Range | Default | Description |
|---|---|---|---|---|
| mode | string | emotion, quality, studio | emotion | Standard engine mode. quality and studio cost ×2 credits. See Engines & Modes above. |
| temperature | integer | 0 – 100 | 25 | Controls speech variability and expressiveness. Lower values produce more stable and predictable speech, while higher values increase variation, spontaneity, and creative phrasing. |
| voice_similarity | integer | 0 – 100 | 100 | Determines how closely the generated speech matches the selected voice profile. Higher values preserve the original voice identity, while lower values allow more deviation in tone and articulation. |
| speed | float | 0.7 – 1.2 | 1.0 | Adjusts the speaking rate. Values below 1.0 slow down speech for clarity, while values above 1.0 increase speaking speed. Studio mode only; ignored in emotion and quality. |
| enable_emotions deprecated | boolean | false / true | — | Still accepted for compatibility but no longer changes the output. Use mode instead. |
| fast_mode deprecated | integer | 0, 1, or 2 | — | Still accepted for compatibility but no longer changes the output; emotion mode is already the fast option. For real-time audio use the streaming endpoint. |
In emotion and quality modes, temperature and voice_similarity are the voice controls (any value in range is used as-is); speed applies to studio mode only.
Advanced engine voices
| Parameter | Type | Values | Description |
|---|---|---|---|
| context | string | up to 500 characters | The strongest control. Describe accent, feeling, mood or purpose, e.g. “A warm documentary read in a Levantine dialect.” |
| setting | string | up to 500 characters | Scene and mood, e.g. “A calm, intimate late-night studio.” |
| style | string | neutral, warm, energetic, serious, cheerful, poetic | Overall delivery style. |
| pace | string | slow, normal, fast | Speaking pace. |
Advanced engine voices ignore mode and the Standard engine sliders, and return the requested output_format. Generation can take a little longer than the Standard engine.
Voice Settings Rules & Constraints
- Unknown keys, an invalid mode, style or pace, or a context/setting longer than 500 characters are rejected with 400 INVALID_REQUEST.
-
For compatibility, when the deprecated enable_emotions is true the following fields must not be included in voice_settings:
speed,fast_mode.
Pricing
Credits = characters × (prerecording rate + voice fee %) × mode multiplier. The multiplier is ×2 for quality and studio, ×1 for emotion, and ×1.5 for every Advanced engine voice.
Example
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
Response
Returns binary audio data in the requested output_format (MP3 by default) with these headers:
| Header | Description |
|---|---|
Content-Type |
Matches output_format: audio/mpeg for mp3_*, audio/ogg for opus_* (Ogg/Opus), audio/pcm;rate=N;channels=1 for pcm_* (raw 16-bit little-endian, no header). |
Errors
| Status | Code | Description |
|---|---|---|
400 |
INVALID_REQUEST | Invalid parameters (including an unknown mode, style or pace) |
401 |
UNAUTHORIZED | Invalid API key |
402 |
INSUFFICIENT_CREDITS | Not enough credits |
429 |
RATE_LIMIT_EXCEEDED | Too many requests |
For API-related questions or issues, contact us at api@moknah.io.