Moknah Docs
Start free
API Reference

Text to Speech (TTS)

Convert text to natural-sounding speech

POST /api/v1/tts/generate/

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
API Support

For API-related questions or issues, contact us at api@moknah.io.