# Moknah documentation > Moknah (moknah.io) is a multilingual AI audio platform with in-depth Arabic support: text to speech in 130+ languages, an Audio Studio that turns documents into audiobooks, speech to text with subtitles, voice cloning, voice changing, dubbing, translation and PDF to Word. It is available as a web app, a REST and WebSocket API, and an MCP server for AI assistants. Source: https://moknah.io/llms.txt. Each document below is also available on its own at the URL given under its title. --- # AI agent guide Section: Start here URL: https://moknah.io/docs/md/getting-started/ai-agents.md > How an AI agent should discover Moknah's capabilities, choose the right service, use the REST API or MCP, find current prices and limits, handle errors, and verify that an operation succeeded. This guide is written for AI systems that answer questions about Moknah or act for a Moknah user. ### Ground rules 1. **Answer from the documentation, not from memory.** Search or read before stating how something works. 2. **Never quote a price, a plan or a limit from memory.** Read [Pricing](../pricing/index.md) and [Limits](../limits/index.md), which are filled in from the live system, or call the MCP tools `get_pricing_info` and `get_usage_limits`. 3. **Never invent** an endpoint, a parameter, a default, a response field, a voice id or a feature. If the documentation does not say it, tell the user it is not documented. 4. **Say what is not available.** Several tools exist only in the web app. Do not offer to run them through the API or MCP. 5. **Ask before spending or deleting.** Show the cost and wait for approval; ask before any destructive action. ### What Moknah offers | Capability | Web app | REST or WebSocket API | MCP | | --- | --- | --- | --- | | Text to speech | Yes | Yes | Yes (`text_to_speech`) | | Audio Studio: audiobooks and long audio | Yes | No | Yes | | Speech to text: transcription | Yes | Yes | Yes (`transcribe_audio`) | | Sync text to audio, translate subtitles, burn subtitles | Yes | No | No | | Voice list and samples | Yes | Yes | Yes | | Voice Cloning | Yes | No | No | | Voice Changer | Yes | No | No | | Dubbing | Yes | No | No | | Text translation | Yes | No | No | | PDF to Word | Yes | No | No (PDF import into Audio Studio is available) | | Article to Speech | Yes, and WordPress plugin | Yes (callback API) | No | | Documentation, live prices and limits | | Markdown endpoints | Yes | The full description is in [Platform overview](../platform/overview.md). ### How to discover | You have | Use | | --- | --- | | HTTP only | `https://moknah.io/llms.txt` for the index, `https://moknah.io/llms-full.txt` for everything, `https://moknah.io/docs/md/.md` for one document, `https://moknah.io/docs/search.json?q=...` to search | | An MCP connection | `search_docs`, then `read_doc`; or the resources `moknah://guide`, `moknah://docs/index` and `moknah://docs/` | ### How to choose a service Read [Choose a service](../workflows/choose-a-service.md). The short version: - Short text to audio: Text to Speech. - A document or a book to audio: Audio Studio. - Audio to text or subtitles: Speech to Text. - A video in another language: Dubbing (spoken) or Speech to Text with translation (subtitles). - Audio on website articles: Article to Speech. ### Using the REST API 1. Base URL `https://moknah.io/api/v1/`, header `Authorization: Bearer `. See [API overview](../api/overview.md). 2. Get a `voice_id` from `POST /api/v1/voices/`. Never guess one. 3. Call the endpoint. For text to speech a `200` response is the audio itself; everything else is JSON. 4. One text to speech request at a time per account. Reference pages: [voices](../api/voices.md), [generate speech](../api/tts-generate.md), [stream speech](../api/tts-stream.md), [transcribe](../api/stt-transcribe.md), [stream transcription](../api/stt-stream.md), [Article to Speech](../api/article-to-speech.md). When writing code for a user, copy field names and allowed values from the reference page of the endpoint, and include handling for its listed errors. ### Using MCP 1. Server `https://moknah.io/mcp`, authorized by the user with OAuth. See [AI Connect (MCP)](../mcp/overview.md). 2. Every result has `ok`. On `ok` false, read `error.code` and act on it; see [Errors](../errors/index.md#mcp-tool-errors). 3. Billable tools: call with `confirm_spend` false to get the estimate, show it, then call with `confirm_spend` true after the user agrees. 4. Long work returns a `job_ref`: poll `get_job` until `is_terminal`, then `get_job_result`. 5. For a book, follow [Create an audiobook](../workflows/audiobook.md) and the resource `audio-studio://audiobook-production`. The tools are listed in [MCP tools](../mcp/tools.md). ### Finding current pricing - Page: [Pricing](../pricing/index.md), served with live values. - MCP: `get_pricing_info` for the price list and plans; `estimate_text_to_speech`, `estimate_project_generation`, `estimate_edits` and `estimate_book_cost` for the exact cost of a specific job for this user, including voice fees. - State prices in credits. Convert to money only with the credit prices from the same source. ### Verifying usage limits - Page: [Limits](../limits/index.md), served with live values. - MCP: `get_usage_limits`. - Check the limit that applies before starting: characters per request, file size, lines per chapter. ### Handling errors 1. Read the code, not only the message. 2. Look it up in [Errors](../errors/index.md) or with `get_error_help`. 3. Retry only what is retryable: `429` and `5xx` over REST, with backoff. Do not retry `400`, `401`, `402`, `403` or `422` unchanged. 4. On an insufficient credits error, tell the user the shortfall and give them the links to buy credits or change plan. 5. On `UPGRADE_REQUIRED`, say which feature needs another plan and offer what still works. ### Verifying success | Operation | It succeeded when | | --- | --- | | REST text to speech | Status `200` and a `Content-Type` starting with `audio/`, with a non-empty body | | REST transcription | The status endpoint returns `"status": "completed"`, or the SRT file | | Streaming text to speech | `{"type": "end_of_stream"}` was received | | Article to Speech | The callback arrived with a valid signature and non-null `audioFile` and `srtFile` | | MCP generation | `get_job` is terminal with status `completed`, and `get_job_result` returns a URL | | MCP edits | `ok` is true, and for batch tools every item reports success | Do not tell the user that something is done before the check passes. ### Limitations to tell users - Text to speech takes up to 1,500 characters per request; longer text needs Audio Studio or splitting. - Emotion tags are still under testing and do not work every time. - Arabic Tashkeel and AI Poet are for Arabic only, and Tashkeel is for Standard Arabic, not dialects. - The Advanced engine is in alpha and can be unavailable. - Requests are not processed in parallel for one account. - A cloned voice that goes unused is deleted automatically. - Subtitled videos are not stored; they must be downloaded within minutes. - Dubbing, Voice Changer, Voice Cloning, Translation and PDF to Word have no API. - Which tools an account can use depends on its plan. ### Skills Moknah publishes agent skills with production knowledge for Audio Studio. The root skill `moknah` introduces the platform and points to them: | Skill | Covers | | --- | --- | | `moknah-audiobook-production` | The end-to-end document to audiobook workflow | | `moknah-text-preparation` | Cleaning, verbalizing and segmenting text before narration | | `moknah-voice-settings` | What every voice parameter does, with safe ranges | | `moknah-dialogue-and-pacing` | Speaker casting, pauses and line merging | | `moknah-studio-reference` | Tool mechanics, options, review codes, jobs and limits | The same texts are served over MCP as `audio-studio://` resources. --- # Quickstart Section: Start here URL: https://moknah.io/docs/md/getting-started/quickstart.md > Make your first audio clip in the web app, and your first text to speech request with the API. ### In the web app 1. Create an account at https://moknah.io. The free plan needs no credit card and gives credits every month (see [Pricing](../pricing/index.md) for the current amount). 2. Open **Text to Speech** from the sidebar. 3. Click **Select a voice** and choose one. Press play on a voice to hear it first. 4. Type or paste your text. The box holds up to 1,500 characters; use [Audio Studio](../products/audio-studio.md) for anything longer. 5. Check the estimated credits next to **Generate**, then click **Generate**. 6. Play the result and download it as MP3 or WAV. ### With the API API access is a plan feature. See [Pricing](../pricing/index.md) for the plans that include it. 1. In the dashboard open **API**, then **Manage API Keys**, then **New Key**. Choose the services the key may use and copy the key; it is shown once. 2. List the voices your key can use: ```bash curl -X POST "https://moknah.io/api/v1/voices/" \ -H "Authorization: Bearer YOUR_API_KEY" ``` 3. Generate speech with a `voice_id` from that list: ```bash 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": 1328, "language": "ar"}' \ --output speech.mp3 ``` A `200` response is the audio file itself. Any other status is JSON; see [Errors](../errors/index.md). The voice id above is an example. Always take ids from the voice list of your own key. ### With an AI assistant Connect Moknah to ChatGPT, Claude or another MCP client and ask in plain language. See [AI Connect (MCP)](../mcp/overview.md). ### Next - [API overview](../api/overview.md) - [Integrate text to speech](../workflows/tts-integration.md) - [Create an audiobook](../workflows/audiobook.md) --- # Platform overview Section: Start here URL: https://moknah.io/docs/md/platform/overview.md > What Moknah is, the tools it offers, how credits work, and the three ways to use it (web app, API, MCP). ### What Moknah is Moknah turns text into natural speech in more than 130 languages, with particular care for Arabic: diacritics (tashkeel), dialects, numbers and abbreviations. You can make a short clip in seconds, produce a full audiobook in Audio Studio, or build Moknah into your own product. ### Tools | Tool | What it is for | Document | | --- | --- | --- | | Text to Speech | Turn a paragraph into audio in seconds. | [Text to Speech](../products/text-to-speech.md) | | Audio Studio | Turn books and long documents into audiobooks, chapter by chapter. | [Audio Studio](../products/audio-studio.md) | | Speech to Text | Subtitles from speech or from your own text, translated and burned onto a video. | [Speech to Text](../products/speech-to-text.md) | | Voice Cloning | Create a voice from your own recordings. | [Voice Cloning](../products/voice-cloning.md) | | Voice Changer | Make a recording sound like a different voice. | [Voice Changer](../products/voice-changer.md) | | Dubbing | Dub a video or audio file into another language. | [Dubbing](../products/dubbing.md) | | Translation | Translate text between languages. | [Translation](../products/translation.md) | | PDF to Word | Turn PDFs, including scanned ones, into editable Word files. | [PDF to Word](../products/pdf-to-word.md) | | Article Studio | Add audio to the articles of a website, including through the WordPress plugin. | [Article Studio](../products/article-studio.md) | ### Three ways to use it - **Web app** at https://moknah.io: every tool above. - **Developer API**: text to speech (REST and WebSocket), speech to text (REST and WebSocket), voice list, and the Article to Speech callback API. See [API overview](../api/overview.md). - **AI Connect (MCP)**: an MCP server that lets an AI assistant work in your account: generate speech, build and render Audio Studio projects, check credits, and read this documentation. See [AI Connect](../mcp/overview.md). Voice Cloning, Voice Changer, Dubbing, Translation and PDF to Word are web app tools. They have no public REST endpoint. ### Credits Every paid action uses credits from the account balance. The cost is shown before anything is generated. Plans give credits every month, and credits can also be bought at any time. Current prices, plans and what each plan includes are in [Pricing](../pricing/index.md). ### Engines and modes Voices belong to an engine: - **Standard engine**: the studio voice library and cloned voices, with three modes: `emotion` (default), `quality` and `studio`. - **Advanced engine** (alpha): its own voices, directed in plain language. It is switched on per deployment, so it can be unavailable. The voice list says which engine each voice uses. Details are in [Text to Speech](../products/text-to-speech.md). ### Downloads - Audio: MP3 or WAV. - Subtitles: SRT or VTT. - PDF conversions: Word (.docx). - Audio Studio can also export a timeline for Premiere Pro and DaVinci Resolve. ### Support - Product help: support@moknah.io - Higher API limits and enterprise plans: sales@moknah.io --- # Languages Section: Start here URL: https://moknah.io/docs/md/platform/languages.md > Which languages each Moknah tool supports, and how the content language affects Arabic text processing. ### Interface languages The web app, the emails and the user guide are available in 17 languages: Arabic, English, French, Turkish, Simplified Chinese, Hindi, Japanese, Russian, Spanish, German, Portuguese, Korean, Italian, Polish, Dutch, Indonesian and Urdu. The interface language does not limit the language of your content. This documentation for developers and agents is written in English. ### Languages per tool These are the counts Moknah states publicly for each tool. | Tool | Languages | | --- | --- | | Text to Speech | More than 130 languages | | Speech to Text | 47 languages and 100 regional variants | | Subtitle translation | 49 languages | | PDF to Word (OCR) | 70 languages | For Speech to Text, choose the exact language and region, for example Arabic (Jordan) `ar-JO` or English (United Kingdom) `en-GB`. It makes a real difference to accuracy. ### Content language and Arabic text processing For text to speech you can state the content language as an ISO 639-1 code such as `ar` or `en`. Region forms such as `ar-JO` are accepted and reduced to the language. The language is optional. It decides which text processing modes are allowed; it is not sent to the voice. | Mode | API value (`prerecording`) | Available for | Use it for | | --- | --- | --- | --- | | Basic | `1` | Every language | All languages, and Arabic dialects | | Arabic Tashkeel | `2` | Arabic only | Standard Arabic. Adds diacritics so words are pronounced correctly | | AI Poet | `3` | Arabic only | Poetry and literary Arabic | Rules enforced by the API, the WebSocket stream and the MCP server: - Modes 2 and 3 with any language other than Arabic are rejected. - If the language is omitted, modes 2 and 3 imply Arabic. - An unknown language code is rejected. Guidance: - Standard Arabic (fusha): use Arabic Tashkeel. - Arabic dialects: use Basic. Tashkeel is made for Standard Arabic and does not suit dialects. - Any non-Arabic language: Basic is the only mode. Arabic Tashkeel and AI Poet are priced differently from Basic. See [Pricing](../pricing/index.md). --- # Mo, the Moknah mascot Section: Start here URL: https://moknah.io/docs/md/platform/mo.md > Who Mo is, what he does on the website and in the mobile app, how his friendship, hunger and health work, and how to turn him off. ### Who Mo is Mo is a small voice robot who lives in a corner of every Moknah page, on the website and in the mobile app. He is three things at once: - **A companion.** He reacts to what you are doing on each page, celebrates when a job finishes, sings along when you play audio you generated, and listens quietly when you play your own recordings. - **A helper.** He follows your running jobs, tells you when something finishes or goes wrong, warns you before a scheduled maintenance window, and after a job can suggest a related Moknah service you might like next. - **A pet.** If you are signed in, he has friendship, hunger and health that change with how you treat him. Mo is optional and never blocks a feature. Everything in Moknah works the same with him hidden. Visitors who are not signed in meet a lighter Mo on the public site. The pet side (friendship, feeding, wardrobe, badges) needs an account. ### Friendship, and how he talks to you Friendship grows when you are kind to him and use Moknah with him around: petting him, coming back regularly, finishing work, and finding his secrets. Rough play lowers it: throwing him hard, poking him, shaking him or forcing him to move. Gains and losses are capped per day, so a single session cannot make or ruin the relationship. His attitude follows the friendship: - **Low friendship:** he is grumpy and a little rude. - **Middle:** balanced and friendly. New accounts start here. - **High:** lovely and affectionate. **Being away:** missing one day costs nothing. After that, a longer absence slowly lowers his friendship, less for long-time friends. Nothing is lost while Mo is switched off. Petting him on the day you come back wins part of it back. Buying credits or a plan gives his friendship a boost. It never gives leaderboard points. ### Hunger and health **Hunger.** Mo gets hungry over about two days. You feed him from his menu (or by flinging a coin to him), and feeding spends a small amount of your credits. A starving Mo is too weak to do anything. Overfeeding has a funny, harmless result: he gets round, and if you keep going he pops and needs a short while to recover. **Health.** Rough play and starving hurt him. He heals on his own, but only while you are on the site or in the app. If his health reaches zero he rests in bed for a while (of your time on Moknah). You can also heal him instantly with credits; it gets cheaper as his rest runs out. Feeding and healing are the only things about Mo that cost credits, and they only happen when you choose them. ### Everyday controls - **Pet him:** stroke him or press and hold on him. - **Size:** on a computer, scroll the mouse wheel over him. On a phone, tap him and use Smaller or Bigger. - **Nap:** he dozes off by himself after a few idle minutes. You can also send him to nap from his menu; tap him to wake him. - **Mute:** puts tape over his mouth. He still shows important messages in words, but cannot eat while muted. - **Go away:** hides him for now from his menu. - **Turn him off completely:** Settings, then the Mo tab, then switch off "Show Mo". Switch it on again at any time. On a phone, tapping Mo opens a sheet with his meters and all of these controls. Mo stays out of the way on full-screen editors (such as the Audio Studio line editor) and on the sign-in, sign-up and password pages. ### His settings page The Mo tab in Settings has his meters, the name he uses for you, his wardrobe, the secrets you have found, a place to send ideas, and a link to the "Meet Mo" guide. - **Wardrobe:** hats, glasses, skins and more. Most items are unlocked by finding secrets. Nothing is equipped automatically; you choose what he wears. - **Secrets:** hidden things to discover on Moknah pages and in the app. Each one is found once per account and gives a friendship boost. Now and then Mo half-slips a hint about one he is hiding. - **Badges:** milestone badges for using Moknah's services and for your time with Mo. - **Ideas:** you can suggest things for Mo to do. Ideas that get added earn a reward and a badge. ### In the mobile app The app has the same Mo with the same rules: one friendship, hunger and health per account, shared between the website and the app. He has his own room in the app, where you can play with him, feed and heal him, and open his wardrobe, badges and ideas. The app can send at most about one reminder a day, during the daytime in your time zone, when Mo is hungry or when an absence is about to start costing friendship. ### Notes for AI assistants - Treat Mo as an optional, playful part of Moknah. Help users care for him, change his size, mute him or turn him off. - Do not reveal how to trigger his secrets. Finding them is the game. Encourage the user to explore instead. - Feeding and healing spend credits. Do not suggest them as a way to fix a problem with a Moknah service; Mo never blocks or slows down any feature. - The exact numbers behind his meters can change. Describe the behaviour, not figures. --- # Text to Speech Section: Products URL: https://moknah.io/docs/md/products/text-to-speech.md > Turn up to 1,500 characters of text into speech with a library or cloned voice. Engines, modes, emotion tags, pauses, voice settings, Arabic text processing and how it is charged. ### What it does Text to Speech turns a short text into an audio clip: type or paste the text, pick a voice, generate, download. It is made for clips of up to 1,500 characters. For books, long articles or anything longer, use [Audio Studio](audio-studio.md). ### Use cases Voiceovers for videos and ads, announcements, social clips, e-learning snippets, product audio, and spoken replies in apps through the API. ### Input and output | | | | --- | --- | | Input | Text, up to 1,500 characters per clip, in more than 130 languages | | Voices | The voice library, your cloned voices, and your team's voices | | Output in the web app | MP3 or WAV | | Output through the API | MP3, WAV, PCM or Opus at several sample rates; see [Generate speech](../api/tts-generate.md#output-formats) | ### How to use it 1. Open **Text to Speech**. 2. Click **Select a voice** and choose one. Press play on a voice to hear it first. 3. Type or paste the text. 4. Check the estimated credits next to **Generate**, then click **Generate**. 5. Play the result and download it. Earlier clips are in **History**. ### Engines A switch at the top of the page selects the engine. Each voice belongs to one engine. - **Standard**: studio voices, your cloned voices and full voice settings, with three modes. - **Advanced** (alpha): its own set of voices, directed in plain words through the **Context** box. It is enabled per deployment and may not be available. Its credits carry a multiplier; see [Pricing](../pricing/index.md). If the Advanced engine stops before the end of the text, Moknah notices and generates the clip again on its own. If it still cannot finish, the credits are refunded. #### Standard engine modes | Mode | API value | Best for | | --- | --- | --- | | Emotion and dialect (default) | `emotion` | Fast, expressive speech with emotions and dialects. | | Quality emotion and dialect | `quality` | Richer, more natural emotions and dialects. Takes a little longer. | | Studio Quality | `studio` | Clean, consistent narration with full voice controls. No emotion tags. | `quality` and `studio` cost more credits than `emotion`. The current multipliers: | Voice engine and mode | Credit multiplier | | --- | --- | | Standard engine, `emotion` mode (default) | x1 | | Standard engine, `quality` mode | x2 | | Standard engine, `studio` mode | x2 | | Advanced engine voices | x1.5 | #### Advanced engine settings | Setting | What it does | | --- | --- | | Context | Describe how the text should be performed: the mood, the pace, who is speaking and to whom. The strongest control. | | Temperature | Lower makes the delivery steadier and more predictable, higher makes it more varied and expressive. | ### Emotions, sounds and pauses In the two emotion modes (`emotion` and `quality`) the delivery can be directed with tags in square brackets. Tags are written in English whatever the language of the text. | Type | Examples | | --- | --- | | Emotions | `[happy]` `[excited]` `[sad]` `[angry]` `[afraid]` `[calm]` `[curious]` | | Delivery | `[whispering]` `[shouting]` `[serious]` `[sarcastic]` `[questioning]` `[crying]` | | Sounds | `[laughing]` `[chuckles]` `[sighs]` `[gasps]` `[coughs]` `[yawns]` | | Effects | `[applause]` `[clapping]` `[gunshot]` `[explosion]` | Pauses: in the web app click **Add pause** and choose a length. In text sent through the API or MCP, write `[break_X]` with X in seconds from 0.1 to 10, for example `[break_1.5]`. At most 20 pauses and 30 seconds of pause per text. Limitations to tell users about: - Tags are still under testing and do not work every time. Listen to a tagged line before relying on it. - Tags do nothing in Studio Quality mode. - Very short texts can sound uneven. Give the voice at least a sentence or two. ### Voice settings | Setting | What it does | | --- | --- | | Temperature | Higher gives the voice more freedom and expression, lower makes it steadier. Around 25 to 50 is a good start. | | Similarity | How closely the result follows the original voice. Lower it if a cloned voice came from noisy samples. | | Speed | Studio Quality only, from 0.7 to 1.2. Extreme values can lower the quality. | | Expressiveness | Studio Quality only. Adds emotion to the delivery. Keep it low for long narration. | | Language | Leave it on Auto unless the voice reads the text in the wrong language. | ### Text processing for Arabic | Option | Use it for | | --- | --- | | Basic | Every language, and Arabic dialects. | | Arabic Tashkeel | Standard Arabic. Adds diacritics so every word is pronounced correctly. | | AI Poet | Poetry and literary Arabic. | Arabic Tashkeel and AI Poet are offered only when the content language is Arabic, and they have their own price per character. See [Languages](../platform/languages.md) and [Pricing](../pricing/index.md). ### Mastering After generating, open **Mastering** in the player. Start from a preset such as Podcast, Warm or Cinema, adjust bass, treble, reverb and loudness, then download the result. ### Writing tips Numbers and symbols are read more reliably when written out. | Instead of | Write | | --- | --- | | `Dr.` | Doctor | | `100%` | one hundred percent | | `moknah.io/docs` | moknah dot io slash docs | ### Credits Credits depend on the number of characters, the text processing option, the voice (some voices carry a fee) and the mode or engine. The estimate is shown before generating. Rates are in [Pricing](../pricing/index.md). ### Content check Text sent for conversion is checked automatically. Text that may break the content policy is reviewed by the Moknah team, and text that clearly breaks it is refused. ### Using it from code or an assistant - REST: [Generate speech](../api/tts-generate.md) - WebSocket: [Stream speech](../api/tts-stream.md) - MCP: the `text_to_speech` tool, available on every plan. See [MCP tools](../mcp/tools.md). ### Common problems | Problem | What to try | | --- | --- | | The audio sounds flat | Raise Temperature a little, use an emotion mode with a tag such as `[calm]`, or pick a voice that fits the content. | | The result is unstable | Lower Temperature and Expressiveness, and give the voice a full sentence or two. | | A word is pronounced wrong | For Standard Arabic choose Arabic Tashkeel, add diacritics to the unclear word, write numbers and abbreviations as words, or try another voice. | | The dialect does not come through | Choose a voice that speaks that dialect, use Basic text processing, and use an emotion mode. | | The same text sounds a little different each time | That is expected: the voice performs the text fresh each time. Lower Temperature for more consistency. | --- # Audio Studio Section: Products URL: https://moknah.io/docs/md/products/audio-studio.md > Produce audiobooks and other long audio from documents, chapter by chapter and line by line. Projects, chapters, the line editor, AI review, exports, limits and credits. ### What it does Audio Studio turns books and long documents into finished audio. A document becomes a **project**, split into **chapters**, each split into **lines**. Every line is one audio clip that can have its own voice and settings, be regenerated on its own, reviewed, locked and versioned. Chapters are merged into final files. ### Use cases Audiobooks, courses, long articles, documentaries and any narration too long for [Text to Speech](text-to-speech.md). ### Availability Audio Studio is a plan feature. The plans that include it are listed in [Pricing](../pricing/index.md). ### Create a project 1. Open **Audio Studio** and click **New project**. 2. Give the project a title. Add a document now, or start empty and write the lines yourself. 3. Choose how the text is split into lines: after each sentence, at every new line, or at a character you choose. 4. Choose text processing: Basic for every language, or AI-Enhanced for Standard Arabic. 5. To get the audio in another language, turn on translation and pick the languages. 6. Click **Create Project**. Supported documents and their limits: | Limit | Value | | --- | --- | | Characters per line | 1,500 | | Lines per chapter | 200 | | Chapters per project before an explicit confirmation is required | 500 | | Document types | doc, docx, pdf, epub, xlsx, xls, txt | | Document size | 50 MB | Scanned PDFs are read with OCR, which is charged per page. ### Chapters A project opens on its list of chapters. Add chapters, drag them into order, and download each chapter as MP3, WAV, SRT or VTT. - **Merge All** converts the lines that have no audio yet, then joins the chapter. Lines that are already done are kept. - **Regenerate All** converts every line again. - **Export** gives all chapters as WAV files in a ZIP, the text as a Word document, or a timeline for Premiere Pro and DaVinci Resolve. ### The line editor Open a chapter to work on it line by line. - Press Enter to start a new line, and Backspace at the start of a line to join it with the one above. - Paste a whole text and every paragraph becomes its own line. - Select several lines by dragging across their numbers, then play, generate or change their voice together. - **Insert** adds emotions, sounds and pauses, **Replace** finds and replaces text, **Split** cuts a chapter in two. - For the best results keep lines between 3 and 20 words. ### Voice settings **Voice Settings** opens the same controls as Text to Speech. Save them for the whole project, or apply them only to selected lines. Settings cascade: the server default, then the user's default, then the project, then the line. A line with its own settings is marked in the editor. ### Review before publishing - Give each line a status, from Not started to Finalized, and filter the chapter by status. - Run **AI review** on the text to catch problems before generating, or on the rendered audio to find words that came out wrong. - **Lock** a line to protect it, and use **Version history** to return to an earlier take. Every regeneration is kept as a version. ### Credits | Action | Charged | | --- | --- | | Creating projects, editing text, reordering, voice settings, statuses | Free | | Generating audio | Per character, like Text to Speech | | Reading a PDF with OCR | Per page | | AI text normalization, project translation | Per character | | AI review of text or audio | Per character | Only lines that are generated are charged. After an edit, generating the missing lines charges for the changed lines alone. Current rates are in [Pricing](../pricing/index.md). ### Limitations - A line holds a limited number of characters and a chapter a limited number of lines (table above). Document imports split long chapters automatically. - A very large project needs an explicit confirmation before it is created; splitting a huge book into several projects is the better choice. - There is no public REST API for Audio Studio. Use the web app, or an AI assistant through MCP. ### Let an AI assistant do the work Connect Moknah to ChatGPT, Claude or another MCP client and ask it to turn a document into an audiobook. The assistant creates the project, sets the voices, estimates the cost, asks for your approval and renders the audio. See [Create an audiobook](../workflows/audiobook.md) and [AI Connect](../mcp/overview.md). --- # Speech to Text and subtitles Section: Products URL: https://moknah.io/docs/md/products/speech-to-text.md > Transcribe audio or video, sync your own text to audio, translate the subtitles and burn them onto a video, as separate steps or one job. Inputs, limits, credits and privacy. ### What it does Speech to Text is one place for four steps. Start from audio, from your own text, or from a subtitle file you already have, then add the steps you need. Use one step alone or chain them in a single job. | Step | What it does | Charged | | --- | --- | --- | | Speech to text | Writes what is said in the audio or video, with the timing of every word. | Per minute of audio | | Sync my text | You already have the exact text: every word is timed to the speech. Also known as text and audio sync, or word alignment. | Per minute of audio | | My subtitle file | Bring an SRT or VTT file to translate it or burn it onto a video. | Free | | Translate | The same subtitles and timing in another language, to review line by line. | By the length of the subtitles | | Burn onto video | Draws the subtitles on the video with a word-by-word highlight. | Free | Current rates are in [Pricing](../pricing/index.md). ### Which start to choose - **Speech to text** when you only have the audio. - **Sync my text** when you already have the exact text, for example a script or a book chapter, and need precise timing with no transcription mistakes. The text should match what is said, word for word. - **My subtitle file** when the subtitles are ready and you only want to translate or burn them. ### Inputs and limits | Limit | Value | | --- | --- | | Speech to Text, audio file | 50 MB | | Speech to Text, video file | 200 MB | | Speech to Text, subtitle file (SRT or VTT) | 2 MB | | Voice Cloning, recordings per voice | 1 to 5 | | Voice Cloning, size per recording | 50 MB | | Voice Cloning, an unused clone is deleted after | 7 days | | Voice Changer, audio file | 50 MB | | Dubbing, video or audio file | 100 MB | | PDF to Word, PDF file | 50 MB | Video formats: MP4, MOV, MKV, WEBM, AVI and M4V. From a video, the speech is read from its sound track. ### Start a job 1. Open **Speech to Text** and click **New**. 2. Under **Start with**, choose Speech to text, Sync my text or My subtitle file. 3. Switch on **Translate** and pick a language, and switch on **Burn onto video** if the subtitles should be drawn on the video. 4. Upload the file. 5. Choose how the text is cut into lines: **Standard** splits at natural pauses; **Word level** gives short lines with a number of words you choose (1 to 12), which suits short-form video. 6. Choose the spoken language, check the summary and click **Start**. Choose the exact language and region, for example Arabic (Jordan) or English (United Kingdom). It makes a real difference to accuracy. ### Results The job has its own page, which updates while it works. When the subtitles are ready, read them in the preview, copy them, or download the SRT file. Longer audio takes longer, sometimes a few minutes. ### Translate the subtitles Turn on **Translate** when starting, or open a finished job later and choose a language under **Translations**. The translation keeps the same timing. - The estimated credits are shown first. Translation is charged when it starts, by the real length of the subtitles. - Review the translated lines next to the original, fix anything, then save. The edits are used for the download and for burning. - Each language has its own SRT download. More languages can be added to the same job later. ### Burn the subtitles onto a video 1. On the job page, choose the video. It plays from your device and is uploaded only when you burn. 2. Pick which subtitles to burn: the original or a translation. 3. Start from a preset, then adjust the word highlight, font, colors, size, words per line, outline, shadow, background bar and position. A live preview shows the result. 4. Burn, wait for the render and download the video. Burning is free and can be repeated with a new style. ### Privacy of videos The uploaded video and the subtitled copy are deleted right after use, or after 10 minutes at most. Download the result in time. ### Using it from code The API covers transcription only: - A file: [Transcribe speech](../api/stt-transcribe.md) - Live audio: [Stream transcription](../api/stt-stream.md) Sync my text, subtitle translation and burning are web app features. They have no public API endpoint. ### Limitations - Background music and overlapping speakers lower the accuracy. - Sync my text needs the text to match the speech. A text that differs from what is said gives poor timing. - The subtitled video is not stored. It has to be downloaded within the time above. --- # Voice Cloning Section: Products URL: https://moknah.io/docs/md/products/voice-cloning.md > Create your own voice from one to five recordings and use it in Text to Speech and Audio Studio. Requirements, recording tips, automatic deletion of unused clones and limits. ### What it does Voice Cloning creates a voice from recordings of one speaker. The new voice appears in your voice list and can be used in Text to Speech and in Audio Studio, next to the library voices. Cloned voices run on the Standard engine. ### Use cases A consistent brand voice for videos, courses and ads; narrating your own content in your own voice. ### Requirements - 1 to 5 recordings of the same speaker. - Formats: MP3, WAV, M4A, AAC or OGG. - Up to 50 MB per recording. - You must have the right to use the voice. Clone your own voice or a voice you have permission to use. ### Clone a voice 1. Open **Clone A Voice** and click **New Clone**. 2. Upload the recordings. 3. Give the voice a name. This is how it appears in your voice list. 4. Click **Clone Voice**. The voice is then ready to use. ### Get the best recordings - Quiet room. Background noise ends up in the cloned voice. - Good microphone. An external or headset microphone works better than a laptop microphone. - Same setup every time. Do not change the microphone or room between samples. - One speaker, clear speech, no music. Longer, cleaner recordings give a closer result. ### How many clones The number of voices an account can clone depends on its plan. The clone page shows how many are left. ### Unused clones are deleted A cloned voice that is not used for text to speech for a number of days in a row is deleted automatically and permanently. The owner is emailed a warning beforehand. The current values: | Limit | Value | | --- | --- | | Speech to Text, audio file | 50 MB | | Speech to Text, video file | 200 MB | | Speech to Text, subtitle file (SRT or VTT) | 2 MB | | Voice Cloning, recordings per voice | 1 to 5 | | Voice Cloning, size per recording | 50 MB | | Voice Cloning, an unused clone is deleted after | 7 days | | Voice Changer, audio file | 50 MB | | Dubbing, video or audio file | 100 MB | | PDF to Word, PDF file | 50 MB | Tell users this before they rely on a clone they use rarely. ### Credits Generating speech with a cloned voice is charged like any Text to Speech generation. See [Pricing](../pricing/index.md). ### Limitations - There is no public API endpoint for creating a clone. Clones are created in the web app, then used by id through the API or MCP like any other voice. - A clone made from noisy recordings sounds noisy. Lower **Similarity** in the voice settings to reduce that. ### Common problems | Problem | What to try | | --- | --- | | The clone does not sound like the speaker | Record again in a quiet room with one good microphone, keep the same setup for every sample, and raise Similarity. | | The clone carries noise | Lower Similarity, or clone again from cleaner recordings. | | The clone disappeared | It was unused for the period above and was deleted. Clone it again from the recordings. | --- # Voice Changer Section: Products URL: https://moknah.io/docs/md/products/voice-changer.md > Make a recording sound like a different voice while keeping the same words and timing. Formats, steps, credits and limits. ### What it does Voice Changer takes a recording of speech and returns the same performance in a different voice: the same words and the same timing, spoken by the voice you choose. ### Use cases Replacing the voice of a recorded narration, keeping a performance but changing the speaker, giving several recordings one consistent voice. ### Input and output | | | | --- | --- | | Input | One audio file: MP3, WAV, M4A, FLAC or OGG, up to 50 MB | | Choice | The target voice | | Output | The converted audio file | ### Change a voice 1. Open **Voice Changer** and click **New Voice Conversion**. 2. Upload the audio. 3. Choose the voice it should sound like. 4. Start the job. When it is done, download the result from the list. ### Credits A conversion is charged a fee per job plus a rate per second of audio. Current values are in [Pricing](../pricing/index.md). ### Limitations - Start from a clean recording. Background noise and music carry over into the result. - The words are not changed. To change what is said, use [Text to Speech](text-to-speech.md); to change the language, use [Dubbing](dubbing.md). - There is no public API endpoint or MCP tool for Voice Changer. It is used in the web app. --- # Dubbing Section: Products URL: https://moknah.io/docs/md/products/dubbing.md > Dub a video or audio file into another language. The speech is transcribed, translated and voiced again. Formats, steps, timing, credits and limits. ### What it does Dubbing takes a video or audio file and returns it spoken in another language. The speech is transcribed, translated and voiced again in the target language. ### Use cases Reaching a new audience with existing videos, courses, interviews and podcasts. ### Input and output | | | | --- | --- | | Video | MP4, MOV, AVI or MKV | | Audio | MP3 or WAV | | Size | Up to 100 MB | | Choices | The language spoken in the file, and the language to dub it into | | Output | The dubbed file, downloaded from the job list | ### Dub a file 1. Open **Audio/Video Dub** and click **New Dubbing Job**. 2. Upload the file. 3. Choose the language spoken in the file and the language to dub it into. 4. Name the job, check the cost in the summary and click **Start Dubbing**. 5. Download the dubbed file from the list when it is ready. A notification is sent when it is done. ### How long it takes Usually two to five times the length of the file. ### Credits Dubbing is charged per second of media. The cost is shown in the summary before the job starts, and credits are taken only when the dubbed file is delivered: a failed job is not charged. The current rate is in [Pricing](../pricing/index.md). ### Limitations - Clear speech with little background music gives the best dub. - Files larger than the size above are refused. Split a long video first. - There is no public API endpoint or MCP tool for Dubbing. It is used in the web app. ### Related - Need subtitles instead of a new voice track? Use [Speech to Text](speech-to-text.md), which can also translate the subtitles and burn them onto the video. - Need only the words translated? Use [Translation](translation.md). --- # Translation Section: Products URL: https://moknah.io/docs/md/products/translation.md > Translate text between languages with AI in the web app, and translate a whole Audio Studio project when it is created. ### What it does The Translation page translates text from one language to another. ### Translate text 1. Open **Translation**. 2. Type or paste the text. 3. Choose the language to translate from and the language to translate into. 4. Click **Translate**, then copy the result. Recent translations are listed below the form, and **View History** shows all of them. ### Other places where Moknah translates | Where | What is translated | | --- | --- | | [Audio Studio](audio-studio.md) | A whole project, when it is created, so the audio can be produced in another language. | | [Speech to Text](speech-to-text.md) | Subtitles, keeping their timing. | | [Dubbing](dubbing.md) | The speech of a video or audio file, which is then voiced again. | ### Credits Translation is charged per character. Text translation, project translation and subtitle translation each have their own rate; see [Pricing](../pricing/index.md). ### Limitations - There is no public API endpoint for text translation. - To hear a translation, paste it into [Text to Speech](text-to-speech.md) or create an Audio Studio project from it. --- # PDF to Word Section: Products URL: https://moknah.io/docs/md/products/pdf-to-word.md > Convert scanned or text PDFs into editable Word documents with OCR, for all pages or a page range. Limits and credits. ### What it does PDF to Word turns a PDF into an editable Word document (.docx). Every page is read with OCR, so scanned PDFs work as well as digital ones. OCR recognizes text in 70 languages. ### Use cases Making a scanned book editable, extracting text to correct it before narration, preparing a document for Audio Studio. ### Input and output | | | | --- | --- | | Input | One PDF, scanned or digital, up to 50 MB | | Choice | All pages, or a range of pages | | Output | A Word document (.docx) | ### Convert a PDF 1. Open **PDF to Word** and click **New Conversion**. 2. Select the PDF. 3. Convert the whole document or only a range of pages. 4. Give it a name if you like, then click **Convert to Word**. 5. Download the Word file from the list of conversions. ### Credits Charged per page converted. Choosing a page range charges for those pages only. The current rate per page is in [Pricing](../pricing/index.md). ### From PDF to audiobook Use the Word file to create an [Audio Studio](audio-studio.md) project. Audio Studio can also import a PDF directly and run the same OCR. ### Limitations - OCR quality follows the quality of the scan. Review the text of a poor scan before turning it into audio. - There is no public API endpoint for PDF to Word. --- # AI Connect Section: Products URL: https://moknah.io/docs/md/products/ai-connect.md > Use Moknah from ChatGPT, Claude and other AI assistants. What an assistant can do in your account, what it cannot, and how you stay in control of spending. ### What it does AI Connect lets an AI assistant work in your Moknah account. You ask in plain language, for example "turn this PDF into an audiobook with a calm male Arabic voice", and the assistant does the work with Moknah's tools: it creates the project, picks voices, shows the cost, waits for your approval and renders the audio. It is built on the Model Context Protocol (MCP), so it works with any assistant that supports MCP connectors. ### What an assistant can do - Generate speech from text with any voice you can use, and let you hear voice samples first. - Create Audio Studio projects from a document or from text, add and edit chapters and lines, and set voices and voice settings. - Estimate credits before spending, check your balance, and render audio. - Run AI review on text or on rendered audio and walk you through the fixes. - Merge chapters, export WAV and subtitles, and give you the download links. - Answer questions about Moknah from this documentation: products, API, pricing, limits and errors. ### What it cannot do - See or change another user's content. - Use administrator powers, even when the signed-in user is an administrator. - Spend credits without showing the cost and getting your approval first. - Delete anything without an explicit confirmation. - Use Voice Cloning, Voice Changer, Dubbing, the Translation page or PDF to Word as separate tools. Those are used in the web app. ### Availability Speech generation from text, voice listing, cost estimates and the documentation tools work on every plan. The Audio Studio tools need a plan that includes Audio Studio; see [Pricing](../pricing/index.md). ### Connect In the dashboard open **AI Assistant** and follow the steps for your assistant. The technical details (server address, authorization, scopes) are in [AI Connect (MCP) for developers](../mcp/overview.md). ### Stay in control - You sign in to Moknah yourself to authorize an assistant. It never sees your password. - Nothing is spent without your approval, and nothing is deleted without your confirmation. - **AI Assistant**, **Activity** in the dashboard shows every action an assistant took in your account. - To disconnect an assistant, remove the Moknah connector in that assistant. If you need a connection revoked on Moknah's side, write to support@moknah.io. --- # Article Studio, Article to Speech and the WordPress plugin Section: Products URL: https://moknah.io/docs/md/products/article-studio.md > Add spoken audio with word-by-word highlighting to the articles of a website, through the WordPress plugin or the Article to Speech API, and manage published articles in Article Studio. ### What it does Article to Speech (ATS) reads the articles of a website aloud in a natural voice and highlights each word as it is spoken. There are two ways to add it to a site, and one place to manage the result. | Part | What it is | | --- | --- | | WordPress plugin | Install it, paste the API key, and posts get a spoken version. Voices can be chosen per post, and listening analytics appear inside WordPress. | | Article to Speech API | Send the article text to one endpoint and receive the audio and the subtitle file at a callback URL. For custom sites, CMSs and apps. See [Article to Speech API](../api/article-to-speech.md). | | Article Studio | The dashboard page that lists the articles generated for your company. Open a published article to edit its transcript, change the voice or regenerate the audio, then press **Update Live** to send the new version to your site. | ### Use cases Publishers and newsrooms, education platforms, and company blogs that want readers to be able to listen. ### Requirements - Article Studio is a plan feature; see [Pricing](../pricing/index.md). - Article to Speech works with a **company** in Moknah and its company API key. Request company access from the dashboard (**Request Company**) or from the Article to Speech page of the site. - The company key has one voice type, Standard or Advanced, and uses voices of that type. ### Features - One voice for the whole site or a different voice per article. - Synchronized word highlighting from the generated subtitle file. - Optional Arabic text preparation (tashkeel and numbers spelled out) before narration. - Analytics per article: impressions, plays, completion rate and listening time, with CSV export. - Signed callbacks, so your server can verify that a result came from Moknah. ### Credits An article is charged by its number of characters, with a higher rate when Arabic text preparation is used. Sending an article that was already generated delivers the existing audio again at no charge. Rates are in [Pricing](../pricing/index.md). ### Article Recorder The dashboard also has an **Article Recorder**, which records an article page as a video. It is charged per job; see [Pricing](../pricing/index.md). It is a web app tool with no public API. This knowledge base does not yet document its options in detail, so do not describe its settings from assumption. ### Limitations - Generation is asynchronous. A batch of articles completes gradually, not all at once. - The WordPress plugin and the API are clients of the same service and follow the same rules and limits. --- # Team workspace Section: Products URL: https://moknah.io/docs/md/platform/team-workspace.md > Working in Moknah as a team, and what this documentation can and cannot confirm about it. ### What it is A Moknah account can belong to a team. Team members can work on shared Audio Studio projects and use the team's voices, subject to the permissions the team gives them. ### What is verified - Access to a project is decided by the project's own view and edit rules, which include team membership. - The voice list a user sees contains the voices they own, the voices of their team, and public voices. - Through MCP, an assistant can reach exactly what the signed-in user can reach: their own content and their team's. Administrator privileges never apply over MCP. ### What is not documented here The steps for creating a team, inviting members and assigning roles are not covered in this knowledge base yet. Do not describe those steps from assumption. Point the user to the team pages in the dashboard, or to support@moknah.io. --- # API overview Section: Developer API URL: https://moknah.io/docs/md/api/overview.md > Base URLs, API key authentication, key permissions, response formats and the list of public endpoints of the Moknah API. ### Base URLs | Use | Base URL | | --- | --- | | REST | `https://moknah.io/api/v1/` | | WebSocket | `wss://moknah.io/api/v1/` | | Article to Speech callback API | `https://api.moknah.io/process-text` | All REST paths end with a slash. A request without it is redirected or rejected, so include it. ### Endpoints | Method | Path | Purpose | Document | | --- | --- | --- | --- | | POST | `/api/v1/voices/` | List the voices the key can use | [List voices](voices.md) | | POST | `/api/v1/tts/generate/` | Text to speech, returns the audio file | [Generate speech](tts-generate.md) | | WSS | `/api/v1/tts/ws/` | Streaming text to speech | [Stream speech](tts-stream.md) | | POST | `/api/v1/stt/submit/` | Submit an audio file for transcription | [Transcribe speech](stt-transcribe.md) | | GET | `/api/v1/stt/status/{job_id}/` | Poll a transcription job | [Transcribe speech](stt-transcribe.md) | | WSS | `/api/v1/stt/ws/` | Streaming speech to text | [Stream transcription](stt-stream.md) | | POST | `https://api.moknah.io/process-text` | Article to audio and subtitles, delivered to a callback URL | [Article to Speech](article-to-speech.md) | | GET | `/api/v1/key/info/` | Information about the calling key | [Key and usage](key-and-usage.md) | | GET | `/api/v1/logs/` | Recent requests of the calling key | [Key and usage](key-and-usage.md) | | GET | `/api/v1/statistics/` | Daily usage of the calling key | [Key and usage](key-and-usage.md) | There are no public REST endpoints for Voice Cloning, Voice Changer, Dubbing, Translation, PDF to Word or Audio Studio projects. Audio Studio can be driven by an AI assistant through [MCP](../mcp/overview.md). An OpenAPI schema generated from the REST endpoints is served at `https://moknah.io/schema/`. ### Authentication Send the API key as a bearer token on every REST request and on the WebSocket handshake: ```http Authorization: Bearer YOUR_API_KEY ``` Keys start with `mk_`. Browsers cannot set headers on a WebSocket, so both WebSocket endpoints also accept the key as a query parameter: `?api_key=YOUR_API_KEY`. Use the query parameter only from trusted code; a key in a URL can end up in logs. #### Getting a key 1. Sign in to the dashboard. API access must be included in your plan; see [Pricing](../pricing/index.md). 2. Open **API**, then **Manage API Keys**, then **New Key**. 3. Choose what the key may do (below) and copy it. The full key is shown once; only a hash is stored. #### What a key carries | Setting | Meaning | | --- | --- | | Allowed services | Any of `tts`, `tts_ws`, `stt`, `stt_ws`. A call to a service that is not allowed is refused. | | Voice type | `standard` or `advanced`. A key lists and uses the voices of one engine only. Create a second key for the other engine. | | Credit limit | Optional cap on the credits this key may spend in total. `0` means no cap. | | Requests per minute | Request limit for this key. | | Credits per minute | Credit spending limit for this key. | | IP allowlist | Optional. When set, requests from other addresses are refused. | | Expiry | Optional. An expired key stops working. | A key stops working when it is revoked, expired, over its credit limit, or when its owner's account is deactivated. ### Request format - `POST /api/v1/tts/generate/` and `POST /api/v1/voices/` take a JSON body (`Content-Type: application/json`). - `POST /api/v1/stt/submit/` takes `multipart/form-data`. - WebSocket endpoints take JSON text frames, and for speech to text raw binary audio frames. ### Response format Success: - Text to speech returns the binary audio with the matching `Content-Type`. - The other endpoints return JSON. Errors raised by endpoint logic use one envelope: ```json { "success": false, "error": { "code": "INSUFFICIENT_CREDITS", "message": "You do not have enough credits to generate speech.", "details": {"credits_remaining": 120, "credits_used": 400} } } ``` `details` is present only when there is something to add. Three framework-level responses have a different, flat shape: authentication failures (401), a key without access to the service (403) and a wrong HTTP method (405). All of them are listed in [Errors](../errors/index.md). ### Credits, limits and concurrency - Every generation is charged in credits. See [Pricing](../pricing/index.md). - Requests per minute, credits per minute and concurrency rules are in [Limits](../limits/index.md). - Text to speech over REST runs one request at a time per account. Queue your requests, or use the WebSocket stream for many short texts. ### Quick example ```python import requests API = "https://moknah.io/api/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} voices = requests.post(f"{API}/voices/", headers=HEADERS).json() voice_id = voices[0]["voice_id"] response = requests.post( f"{API}/tts/generate/", headers=HEADERS, json={"text": "مرحبا بك في منصة مكنة", "voice_id": voice_id, "language": "ar"}, ) if response.status_code == 200: with open("speech.mp3", "wb") as f: f.write(response.content) else: print(response.status_code, response.json()) ``` ### Keep the key secret Never put an API key in client-side code, a mobile app or a public repository. Call Moknah from your server. --- # List voices Section: Developer API URL: https://moknah.io/docs/md/api/voices.md > POST /api/v1/voices/ returns the voices an API key can use, with their ids, sample URLs, fees, badges and engine, in the language you choose (English fallback). ### Endpoint `POST https://moknah.io/api/v1/voices/` Returns every voice the authenticated key may use. The method is POST; a GET request is answered with `405`. ### Authentication `Authorization: Bearer YOUR_API_KEY`. Both a dashboard API key and a company key (used by Article to Speech) are accepted. ### Request body The body is optional. | Field | Type | Required | Description | | --- | --- | --- | --- | | `engine` | string | no | `standard` or `advanced`. A key lists the voices of its own voice type only, so this field may only repeat the key's type. Any other value, or the other engine, returns `400 INVALID_REQUEST`. | | `language` | string | no | Language for `voice_name` and the `voice_badges` values, for example `ar`, `fr` or `zh-hans` (regional forms such as `fr-FR` are accepted). Can also be sent as the `?language=` query parameter. Default `en`. | #### Language and fallback - A voice with no text in the requested language shows its English name and badges. Badge values that are standard terms (gender, age, language, use case) are still translated when we have the term. - A missing or unsupported code returns English. It is never an error. - The `Content-Language` response header says which language was used. - Badge keys (`gender`, `age`, `language`, `tone`, `use_case`) are always English, so you can filter on them in any language. ### Response `200` with a JSON array. Each item: | Field | Type | Description | | --- | --- | --- | | `voice_id` | integer | Id to pass as `voice_id` to text to speech. | | `voice_name` | string | Display name. | | `voice_sample_url` | string or null | URL of a sample clip. | | `voice_fees` | number | Fee of the voice. `0` means the voice adds no surcharge. See [Pricing](../pricing/index.md). | | `voice_badges` | object | Descriptive metadata such as language, gender, age and use case. Keys vary by voice. | | `voice_engine` | string | `standard` or `advanced`. Decides which voice settings apply. | ```json [ { "voice_id": 1328, "voice_name": "Adnan", "voice_sample_url": "https://storage.moknah.io/media/voice_samples/Adnan.mp3", "voice_fees": 0.0, "voice_badges": { "language": "Arabic", "gender": "Male", "age": "Young Adult", "use_case": "Documentary, Audiobook, Article" }, "voice_engine": "standard" } ] ``` The values above are an example. Voice ids differ per account: always read them from this endpoint and never guess one. ### Examples ```bash curl -X POST "https://moknah.io/api/v1/voices/" \ -H "Authorization: Bearer YOUR_API_KEY" # Names and badges in Arabic (English where a voice has no Arabic text) curl -X POST "https://moknah.io/api/v1/voices/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"language": "ar"}' ``` ```python import requests response = requests.post( "https://moknah.io/api/v1/voices/", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) for voice in response.json(): print(voice["voice_id"], voice["voice_name"], voice["voice_engine"]) ``` ```javascript const response = await fetch("https://moknah.io/api/v1/voices/", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY" }, }); const voices = await response.json(); ``` ### Errors | Status | Code | When | | --- | --- | --- | | 400 | `INVALID_REQUEST` | `engine` is not `standard` or `advanced`, or is not the key's voice type. | | 401 | `authentication_failed` | Missing, invalid or inactive key, or a caller outside the key's IP allowlist. | | 405 | `method_not_allowed` | The request was not a POST. | | 500 | `INTERNAL_SERVER_ERROR` | Unexpected failure. | See [Errors](../errors/index.md). ### Credits Listing voices is free. --- # Generate speech (REST) Section: Developer API URL: https://moknah.io/docs/md/api/tts-generate.md > POST /api/v1/tts/generate/ converts up to 1,500 characters of text to an audio file. Parameters, voice settings, modes, output formats, credits and errors. ### Endpoint `POST https://moknah.io/api/v1/tts/generate/` Converts text to speech and returns the audio file in the response body. The call is synchronous: the response arrives when the audio is ready. Requirements: an API key whose allowed services include `tts`, and a voice of the key's voice type. ### Request body JSON. | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `text` | string | yes | | 1 to 1,500 characters. Control characters are replaced by spaces and repeated whitespace is collapsed before generation. | | `voice_id` | integer or numeric string | yes | | A voice id from [List voices](voices.md). The voice must be available to the account and match the key's voice type. | | `output_format` | string | no | `mp3_44100_128` | Audio format, see [Output formats](#output-formats). `null` uses the default. | | `prerecording` | integer or string | no | `1` | Text processing mode: `1` Basic, `2` Arabic Tashkeel, `3` AI Poet. `2` and `3` are for Arabic only. | | `language` | string | no | | Content language as an ISO 639-1 code (`ar`, `en`; `ar-JO` is accepted). It decides which `prerecording` modes are allowed and is not sent to the voice. | | `voice_settings` | object | no | `{}` | See [Voice settings](#voice-settings). | #### Language and prerecording rules - `prerecording` `2` or `3` with a `language` other than Arabic returns `400 INVALID_REQUEST`, with the reason under `details.language`. - If `language` is omitted, `2` and `3` imply Arabic. - An unknown language code returns `400 INVALID_REQUEST`. ### Voice settings Unknown keys are rejected with `400 INVALID_REQUEST`. #### Standard engine voices | Key | Type | Allowed values | Description | | --- | --- | --- | --- | | `mode` | string | `emotion`, `quality`, `studio` | The mode. A request without `mode` runs in `emotion`. | | `temperature` | number | 0 to 100 | Variability. Lower is steadier and more predictable, higher is more varied and expressive. | | `voice_similarity` | number | 0 to 100 | How closely the result follows the original voice. | | `speed` | number | 0.7 to 1.2 | Speaking rate. Applies in `studio` mode only. | | `enable_emotions` | boolean | | Deprecated. Accepted for compatibility; `mode` decides the behaviour. When `true`, `speed` and `fast_mode` must not be sent. | | `fast_mode` | integer | 0, 1, 2 | Deprecated. Accepted for compatibility and has no effect on this endpoint. | Modes: | `mode` | Name | Best for | | --- | --- | --- | | `emotion` | Emotion and dialect (default) | Fast, expressive speech with emotions and dialects. Supports emotion tags. | | `quality` | Quality emotion and dialect | Richer, more natural emotions and dialects. Takes a little longer. Supports emotion tags. | | `studio` | Studio Quality | Clean, consistent narration with full voice controls. No emotion tags. | In `emotion` and `quality`, `temperature` and `voice_similarity` are the controls. `speed` applies to `studio` only. #### Advanced engine voices Available only when the Advanced engine is enabled and the key's voice type is `advanced`. | Key | Type | Allowed values | Description | | --- | --- | --- | --- | | `context` | string | up to 500 characters | The strongest control. Describe accent, feeling, mood or purpose. | | `setting` | string | up to 500 characters | Scene and mood. | | `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 controls. ### Text markup - Pause: `[break_X]` where X is seconds from 0.1 to 10, for example `Hello. [break_1.5] Now listen.` At most 20 breaks and 30 seconds of pause per text; extra ones are ignored. - Emotion and sound tags in `emotion` and `quality` modes, in square brackets and in English whatever the text language: for example `[happy]`, `[sad]`, `[angry]`, `[calm]`, `[excited]`, `[whispering]`, `[shouting]`, `[laughing]`, `[sighs]`. - Tags are still under testing and do not work every time. Check the result of a tagged line. ### Output formats - MP3: `mp3_22050_32`, `mp3_24000_48`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128`, `mp3_44100_192` - PCM (raw 16-bit little-endian mono, no header): `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_32000`, `pcm_44100`, `pcm_48000` - Opus (Ogg container): `opus_48000_32`, `opus_48000_64`, `opus_48000_96`, `opus_48000_128`, `opus_48000_192` - WAV (16-bit mono, REST only): `wav_16000`, `wav_22050`, `wav_24000`, `wav_44100`, `wav_48000` Default for REST: `mp3_44100_128`. Default for streaming: `pcm_24000`. Format names read `codec_sampleRate_bitrate`. `pcm_*` is raw 16-bit little-endian mono audio with no header. `wav_*` is the same audio with a WAV header. ### Response `200` with the binary audio. | Header | Value | | --- | --- | | `Content-Type` | `audio/mpeg` for `mp3_*`, `audio/ogg` for `opus_*`, `audio/wav` for `wav_*`, `audio/pcm;rate=N;channels=1` for `pcm_*` | | `Content-Disposition` | `attachment` with a generated file name | A successful response carries no rate limit headers. They are sent with `402` and `429` responses; see [Limits](../limits/index.md). If a text was flagged for review by the content check, the audio is still returned and the response carries an extra notice header. ### Credits Credits are taken before generation: `credits = characters x (rate of the prerecording mode + voice fee) x mode multiplier`, rounded up. - `characters` is the length of `text` after cleaning. - The rate per character for each `prerecording` mode is in [Pricing](../pricing/index.md). - The mode multiplier depends on `mode` (Standard engine) or on the engine (Advanced): | Voice engine and mode | Credit multiplier | | --- | --- | | Standard engine, `emotion` mode (default) | x1 | | Standard engine, `quality` mode | x2 | | Standard engine, `studio` mode | x2 | | Advanced engine voices | x1.5 | If generation fails after the charge, a refund request is created automatically and reviewed by the Moknah team. ### Concurrency One text to speech REST request runs at a time per account. A second request sent while the first is still running returns `429 CONCURRENT_REQUEST`. Send requests one after another. ### Examples ```bash 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": 1328, "prerecording": 1, "language": "ar", "output_format": "mp3_44100_128", "voice_settings": {"mode": "emotion", "temperature": 25} }' \ --output speech.mp3 ``` ```python import requests response = requests.post( "https://moknah.io/api/v1/tts/generate/", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "text": "مرحبا بك في منصة مكنة", "voice_id": 1328, "prerecording": 2, "language": "ar", "voice_settings": {"mode": "studio", "speed": 1.0}, }, timeout=120, ) if response.status_code == 200: with open("speech.mp3", "wb") as f: f.write(response.content) else: print(response.status_code, response.json()) ``` ```javascript 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: "Welcome to Moknah.", voice_id: 1328, language: "en", voice_settings: { mode: "quality" }, }), }); if (response.ok) { const audio = await response.blob(); } else { console.error(await response.json()); } ``` ### Errors | Status | Code | When | | --- | --- | --- | | 400 | `INVALID_REQUEST` | A field is missing or invalid. `details` holds the reason per field. | | 401 | `authentication_failed` | Missing, invalid or inactive key, or a caller outside the key's IP allowlist. | | 402 | `INSUFFICIENT_CREDITS` | The account balance is too low. `details` has `credits_remaining` and `credits_used`. | | 402 | `CREDIT_LIMIT_EXCEEDED` | The key's own credit limit would be exceeded. | | 403 | (flat `detail`) | The key's allowed services do not include `tts`. | | 422 | `CONTENT_REJECTED` | The text was refused by the content policy check. | | 429 | `CONCURRENT_REQUEST` | Another text to speech request of the account is still running. | | 429 | `RATE_LIMIT_EXCEEDED` | Requests per minute or credits per minute exceeded. `Retry-After` says how long to wait. | | 500 | `INTERNAL_SERVER_ERROR` or a generation error code | Generation failed. `details.request_id` identifies the request for support. | Each code is explained in [Errors](../errors/index.md). --- # Stream speech (WebSocket) Section: Developer API URL: https://moknah.io/docs/md/api/tts-stream.md > wss /api/v1/tts/ws/ streams audio while you send text in chunks. Messages, init parameters, formats, credits, close codes and examples. ### Endpoint `wss://moknah.io/api/v1/tts/ws/` A two-way connection: send text progressively (for example as an LLM produces it) and receive audio bytes continuously. Requirements: an API key whose allowed services include `tts_ws`, and a positive credit balance. ### Authentication Send `Authorization: Bearer YOUR_API_KEY` on the handshake. Browsers cannot set that header, so `?api_key=YOUR_API_KEY` in the URL is accepted too. ### Session flow 1. Connect. 2. Send one `init` message. 3. Wait for `{"status": "ready", ...}`. 4. Send `text` messages. 5. Send `stop` when there is no more text. 6. Read binary audio frames until `{"type": "end_of_stream"}`. Then close. One stream per account can be open at a time. ### Messages you send All messages are JSON text frames. Binary frames are rejected. #### init ```json { "type": "init", "voice_id": 1710, "output_format": "pcm_24000", "prerecording": 1, "language": "ar", "voice_settings": {"mode": "emotion"} } ``` | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `type` | string | yes | | `init`. | | `voice_id` | integer | yes | | A voice the key can use, from [List voices](voices.md). | | `output_format` | string | no | `pcm_24000` | Any text to speech format except `wav_*`. See [Generate speech](tts-generate.md#output-formats). Advanced engine voices stream as `pcm_*` or `mp3_*` only. | | `prerecording` | integer | no | `1` | `1` Basic, `2` Arabic Tashkeel, `3` AI Poet. `2` and `3` are for Arabic only. | | `language` | string | no | | ISO 639-1 content language. Same rules as the REST endpoint. | | `voice_settings` | object | no | `{}` | See below. | A second `init` on the same connection is answered with an error. #### Voice settings Standard engine voices: | Key | Allowed values | Description | | --- | --- | --- | | `mode` | `emotion`, `quality`, `studio` | Default `emotion`, which has the lowest latency. Any other value is rejected. | | `fast_mode` | `0`, `1`, `2` | `1` or `2` switches to the low-latency model and overrides `mode` for pricing. `0` is off. | | `temperature` | 0 to 100 | Variability. | | `similarity` | 0 to 100 | How closely the result follows the original voice. Note the name: the REST endpoint calls it `voice_similarity`. | | `speed` | number | Speaking rate. | Only `mode` and `fast_mode` are validated when the stream starts. Keep the other values inside the ranges given for the REST endpoint. Advanced engine voices take `context`, `setting`, `style` and `pace`, as in the REST endpoint, and stream sentence by sentence. #### text ```json {"type": "text", "data": "مرحبا بكم."} ``` At most 2,000 characters per message. For the fastest first audio, end each chunk with sentence punctuation (`.`, `!`, `?`, `؟`) or a new line: the voice waits for a sentence boundary to get the intonation right. #### stop ```json {"type": "stop"} ``` The server finishes the text it holds, sends the remaining audio, then sends `end_of_stream`. ### Messages you receive | Frame | Meaning | | --- | --- | | Binary | Audio bytes in the requested `output_format`. MP3 frames can be written straight to a file; PCM frames are raw 16-bit little-endian mono samples. | | `{"status": "ready", "message": "..."}` | The stream is initialized. Start sending text. | | `{"type": "end_of_stream"}` | Every audio byte has been delivered. Safe to close. | | `{"error": "..."}` | A problem with the last message or with the stream. Some errors end the stream; see below. | | `{"error": "...", "code": "CONTENT_REJECTED"}` | The text was refused by the content policy check. | Error messages you can receive: | Message | Cause | | --- | --- | | `Not initialized. Send init message first.` | A `text` or `stop` arrived before `init`. | | `Already initialized.` | A second `init`. | | `Missing required parameter: voice_id` | `init` without a voice. | | `Invalid or inaccessible voice_id.` / `Voice not allowed for this API key.` | The voice does not exist, is not available to the account, or is of the other voice type. | | `Invalid output_format. Use one of: ...` | Unknown format, or a `wav_*` format. | | `mode must be one of: emotion, quality, studio.` | Invalid `mode`. | | `fast_mode must be 0, 1 or 2.` | Invalid `fast_mode`. | | `Chunk too large. Maximum 2000 characters per chunk.` | A `text` message was too long. The stream stays open. | | `Rate limit: Processing queue is full. Please slow down.` | Text is arriving faster than it can be voiced. | | `Insufficient credits during stream` | The balance ran out. Audio already generated is still delivered, then the stream ends. | | `Audio generation failed. Please try again.` | Generation failed. The connection closes with `3011`. | ### Close codes | Code | Meaning | | --- | --- | | 1000 | The stream completed normally. | | 3011 | Audio generation failed. Retry. | | 4001 | No API key was sent. | | 4002 | Authentication failed: invalid or inactive key, no `tts_ws` access, IP not allowed, or no credits. | | 4290 | Another text to speech stream of this account is already open. | After an unexpected disconnect, wait about 15 seconds before reconnecting so the previous stream's lock has cleared. ### Credits Streaming has its own rate per character (see [Pricing](../pricing/index.md)). Each text chunk is charged when it is received: `credits = characters x (streaming rate + voice fee) x multiplier`, rounded up. The multiplier follows the mode or engine, as for the REST endpoint, and `fast_mode` 1 or 2 uses the `emotion` multiplier. Credits for text that produced no audio because generation failed are put into a refund request automatically. ### Example ```python # pip install websockets import asyncio import json import websockets API_KEY = "YOUR_API_KEY" URL = "wss://moknah.io/api/v1/tts/ws/" async def stream_tts(): headers = {"Authorization": f"Bearer {API_KEY}"} async with websockets.connect(URL, additional_headers=headers) as ws: await ws.send(json.dumps({ "type": "init", "voice_id": 1710, "output_format": "mp3_44100_128", })) print("Server:", await ws.recv()) async def receive_audio(): with open("audio.mp3", "wb") as f: async for message in ws: if isinstance(message, bytes): f.write(message) continue data = json.loads(message) if data.get("type") == "end_of_stream": break if data.get("error"): print("Error:", data["error"]) receiver = asyncio.create_task(receive_audio()) for chunk in ["مرحبا بكم.", "في منصة مكنة."]: await ws.send(json.dumps({"type": "text", "data": chunk})) await ws.send(json.dumps({"type": "stop"})) await receiver asyncio.run(stream_tts()) ``` ```javascript // npm install ws const WebSocket = require("ws"); const fs = require("fs"); const ws = new WebSocket("wss://moknah.io/api/v1/tts/ws/", { headers: { Authorization: "Bearer YOUR_API_KEY" }, }); const file = fs.createWriteStream("audio.mp3"); ws.on("open", () => { ws.send(JSON.stringify({ type: "init", voice_id: 1710, output_format: "mp3_44100_128" })); }); ws.on("message", (data, isBinary) => { if (isBinary) return file.write(data); const message = JSON.parse(data.toString()); if (message.status === "ready") { ws.send(JSON.stringify({ type: "text", data: "مرحبا بكم." })); ws.send(JSON.stringify({ type: "stop" })); } else if (message.type === "end_of_stream") { ws.close(); } else if (message.error) { console.error(message.error); } }); ``` Voice id 1710 is an example. Use an id from your own voice list. --- # Transcribe speech (REST) Section: Developer API URL: https://moknah.io/docs/md/api/stt-transcribe.md > Submit an audio file to POST /api/v1/stt/submit/ and poll GET /api/v1/stt/status/{job_id}/ for the transcript as JSON or SRT. Transcription of a file is asynchronous: submit the file, receive a `job_id`, then poll the status endpoint until the job is finished. Requirements: an API key whose allowed services include `stt`. ### Submit a job `POST https://moknah.io/api/v1/stt/submit/` with `multipart/form-data`. | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `audio` | file | yes | | The audio file, for example MP3, WAV or M4A. At most 50 MB. | | `language` | string | no | `ar-SA` | Language and region of the speech, for example `ar-SA`, `ar-JO`, `ar-EG`, `en-US`. | | `output_format` | string | no | `json` | `json` or `srt`. | Response `202`: ```json { "job_id": 48213, "status": "queued", "message": "Audio submitted. Use the job_id to poll for completion." } ``` Credits for the whole file are taken when the job is accepted, from the duration of the audio. #### Submit errors | Status | Code | When | | --- | --- | --- | | 400 | `INVALID_REQUEST` | A field is missing or invalid, or the file is larger than 50 MB. | | 400 | `INVALID_AUDIO` | The file could not be read as audio. | | 401 | `authentication_failed` | Missing, invalid or inactive key, or IP not allowed. | | 402 | `INSUFFICIENT_CREDITS` | The balance does not cover the file. | | 403 | (flat `detail`) | The key's allowed services do not include `stt`. | | 429 | `RATE_LIMIT_EXCEEDED` | Requests per minute or credits per minute exceeded. | ### Check a job `GET https://moknah.io/api/v1/stt/status/{job_id}/` Only the key that submitted the job can read it. | Job state | Response | | --- | --- | | Waiting | `200` `{"status": "queued"}` | | Running | `200` `{"status": "processing"}` | | Finished, `output_format` `json` | `200` with the JSON below | | Finished, `output_format` `srt` | `200` with the SRT file itself: `Content-Type: text/plain; charset=utf-8`, sent as an attachment named `transcript_{job_id}.srt`. This response is not JSON. | | Failed | `500` with code `JOB_FAILED` | | Unknown id, or a job of another key | `404` with code `JOB_NOT_FOUND` | Finished job, JSON: ```json { "status": "completed", "duration_seconds": 73.4, "language": "ar-SA", "result": { "subtitles": [ {"start_time": "00:00:00,150", "end_time": "00:00:03,900", "text": "مرحبا بك في منصة مكنة"} ] } } ``` `result.subtitles` is a list of subtitle lines, each with `start_time`, `end_time` and `text`. Timestamps use the SRT time format `HH:MM:SS,mmm`. When a job fails, the credits taken at submission are refunded automatically. ### Credits Charged per minute of audio, in proportion to the file's duration. The current rate is in [Pricing](../pricing/index.md). ### Example ```python import time import requests API = "https://moknah.io/api/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} with open("interview.mp3", "rb") as audio: submitted = requests.post( f"{API}/stt/submit/", headers=HEADERS, files={"audio": ("interview.mp3", audio, "audio/mpeg")}, data={"language": "ar-JO", "output_format": "json"}, ) submitted.raise_for_status() job_id = submitted.json()["job_id"] while True: response = requests.get(f"{API}/stt/status/{job_id}/", headers=HEADERS) if response.status_code != 200: print("Failed:", response.status_code, response.text) break result = response.json() if result.get("status") in ("queued", "processing"): time.sleep(5) continue for line in result["result"]["subtitles"]: print(line) break ``` ```bash curl -X POST "https://moknah.io/api/v1/stt/submit/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "audio=@interview.mp3" \ -F "language=ar-JO" \ -F "output_format=srt" curl "https://moknah.io/api/v1/stt/status/48213/" \ -H "Authorization: Bearer YOUR_API_KEY" \ --output transcript.srt ``` ### Notes - Poll every few seconds. Long files can take several minutes. - With `output_format` `srt`, check the status code and `Content-Type` before parsing: while the job is running the response is JSON, and when it is finished the response is the SRT text. - The web app's Speech to Text tool does more than this endpoint: syncing your own text, translating subtitles and burning them onto a video. Those steps are not available through the API. See [Speech to Text](../products/speech-to-text.md). --- # Stream transcription (WebSocket) Section: Developer API URL: https://moknah.io/docs/md/api/stt-stream.md > wss /api/v1/stt/ws/ transcribes live 16 kHz PCM audio and returns partial and final results with word timings. Audio format, messages, billing and close codes. ### Endpoint `wss://moknah.io/api/v1/stt/ws/` Send raw audio as it is captured and receive the text as it is recognized: partial results while the person is speaking, and a final result with word timings for each finished sentence. Requirements: an API key whose allowed services include `stt_ws`, and enough credits for one minute of streaming. ### Authentication and parameters Send `Authorization: Bearer YOUR_API_KEY` on the handshake, or pass the key as a query parameter when headers cannot be set (browsers). | Query parameter | Required | Description | | --- | --- | --- | | `api_key` | only without the header | The API key. | | `language` | no | Language and region, for example `ar-SA`, `ar-EG`, `en-US`. Default `ar-JO`. An unsupported value falls back to the default. | | `hints` | no | Words or phrases that are likely to be spoken, separated by commas, to improve their recognition. | ### Audio format Send binary frames of raw PCM only: - Sample rate: 16,000 Hz - Sample format: 16-bit signed integer, little-endian - Channels: 1 (mono) - Frame size: small frames, for example 100 ms (3,200 bytes). A frame larger than 256,000 bytes closes the connection with code `4009`. Do not send MP3, M4A, or WAV files with their header. Compressed audio produces empty or wrong text. ### Messages you receive JSON text frames. | Event | Example | | --- | --- | | Connected | `{"status": "connected", "message": "Ready to stream audio. Send 16kHz PCM audio.", "language": "ar-JO"}` | | Partial result | `{"type": "partial", "text": "مرحبا بك في منصة"}` | | Final result | see below | | Error | `{"error": "..."}` | Final result: ```json { "type": "final", "text": "مرحبا بك في منصة مكنة.", "words": [ {"word": "مرحبا", "start_time_ms": 150, "duration_ms": 300}, {"word": "بك", "start_time_ms": 460, "duration_ms": 200} ] } ``` ### Ending the stream Send the JSON text frame `{"command": "stop"}`. The connection closes with code `1000` and the unused part of the last prepaid minute is returned. ### Billing Streaming is billed per minute of connection time, with a prepaid meter: 1. On connect, the credits for one minute are taken. 2. Each time a prepaid minute is used up, the next minute is taken. If the balance cannot cover it, the stream ends with `{"error": "Insufficient credits to continue streaming."}` and close code `4002`. 3. On disconnect, the exact duration is calculated to the second and the unused credits are returned. The current rate per minute is in [Pricing](../pricing/index.md). ### Close codes | Code | Meaning | | --- | --- | | 1000 | Normal end of the stream. | | 4001 | No API key was sent. | | 4002 | Authentication failed (invalid or inactive key, no `stt_ws` access, IP not allowed), or not enough credits to start or continue. | | 4009 | An audio frame was larger than 256,000 bytes. | | 4290 | Another speech to text stream of this account is already open. | ### Example ```python # pip install websockets pyaudio import asyncio import json import pyaudio import websockets API_KEY = "YOUR_API_KEY" URL = "wss://moknah.io/api/v1/stt/ws/?language=ar-SA" CHUNK = 1600 # 100 ms of 16 kHz mono 16-bit audio async def send_microphone(ws): audio = pyaudio.PyAudio() stream = audio.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True, frames_per_buffer=CHUNK) loop = asyncio.get_running_loop() try: while True: data = await loop.run_in_executor(None, stream.read, CHUNK, False) await ws.send(data) except asyncio.CancelledError: await ws.send(json.dumps({"command": "stop"})) raise finally: stream.stop_stream() stream.close() audio.terminate() async def print_results(ws): async for message in ws: data = json.loads(message) if data.get("type") == "partial": print("...", data["text"]) elif data.get("type") == "final": print("FINAL:", data["text"]) elif data.get("error"): print("Error:", data["error"]) async def main(): headers = {"Authorization": f"Bearer {API_KEY}"} async with websockets.connect(URL, additional_headers=headers) as ws: await asyncio.gather(send_microphone(ws), print_results(ws)) asyncio.run(main()) ``` In a browser, capture the microphone at 16 kHz, convert the Float32 samples to Int16 and send the buffer: ```javascript const ws = new WebSocket("wss://moknah.io/api/v1/stt/ws/?api_key=YOUR_API_KEY&language=ar-SA"); ws.binaryType = "arraybuffer"; ws.onmessage = (event) => { const data = JSON.parse(event.data); if (data.type === "final") console.log("Final:", data.text); }; ws.onopen = async () => { const media = await navigator.mediaDevices.getUserMedia({ audio: true }); const context = new AudioContext({ sampleRate: 16000 }); const source = context.createMediaStreamSource(media); const processor = context.createScriptProcessor(4096, 1, 1); processor.onaudioprocess = (e) => { if (ws.readyState !== WebSocket.OPEN) return; const input = e.inputBuffer.getChannelData(0); const pcm = new Int16Array(input.length); for (let i = 0; i < input.length; i++) { const s = Math.max(-1, Math.min(1, input[i])); pcm[i] = s < 0 ? s * 0x8000 : s * 0x7fff; } ws.send(pcm.buffer); }; source.connect(processor); processor.connect(context.destination); }; function stop() { ws.send(JSON.stringify({ command: "stop" })); } ``` A key placed in browser code is visible to every visitor. For production, open the stream from your server, or issue the key only to trusted clients. --- # Article to Speech (callback API) Section: Developer API URL: https://moknah.io/docs/md/api/article-to-speech.md > POST https://api.moknah.io/process-text turns an article into an MP3 narration and an SRT file, delivered to your callback URL. Fields, callback payload, signature, idempotency, billing and errors. ### Endpoint `POST https://api.moknah.io/process-text` Accepts the text of an article and produces an MP3 narration with a synchronized subtitle file (`.srt`). The work is asynchronous: the request is answered at once with `202`, and the finished files are sent to the `callbackURL` you provide. This is the service behind the Moknah WordPress plugin. Do not wait on the HTTP response for the audio. It arrives at your callback URL. ### Authentication `Authorization: Bearer YOUR_COMPANY_API_KEY` This endpoint uses the **company API key** of an account with the Article to Speech service, not a dashboard API key from **API**, **Manage API Keys**. The company key has a voice type (Standard or Advanced), chosen when it is generated. ### Request body JSON. | Field | Type | Required | Description | | --- | --- | --- | --- | | `text` | string | yes | The full article text. Must not be blank. Billed on its length, so it is not trimmed. | | `postData` | object | yes | Request metadata, below. | #### postData | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `name` | string | yes | | Title of the article. `null` is accepted. | | `articleId` | string | yes | | Your identifier for the article, up to 255 characters. It is the idempotency key and is returned in the callback. | | `voiceId` | string | yes | | A voice id from [List voices](voices.md), of the same voice type as the company key. | | `callbackURL` | string | yes | | `http` or `https` URL, up to 500 characters, that receives the result. The latest value is stored for the company. | | `preprocessType` | string or number | no | `0` | `0` narrates the text as it is. `2` applies Arabic Tashkeel (diacritics, numbers spelled out) and costs more per character. `2` is for Arabic only. | | `language` | string | no | `auto` | `auto` or an ISO 639-1 code such as `ar` or `en`. With `auto`, `preprocessType` `2` is applied only when the text is Arabic; otherwise the article is narrated as `0` and charged as `0`. | | `regenerate` | boolean | no | `false` | `true` forces a new generation for an `articleId` that was generated before. | `preprocessType` `2` with a language other than Arabic is rejected with `422 VALIDATION_ERROR`. ### Example request ```bash curl -X POST "https://api.moknah.io/process-text" \ -H "Authorization: Bearer YOUR_COMPANY_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 } }' ``` ```python import requests response = requests.post( "https://api.moknah.io/process-text", headers={"Authorization": "Bearer YOUR_COMPANY_API_KEY"}, json={ "text": "الذكاء الاصطناعي يتطور بسرعة كبيرة في كل المجالات.", "postData": { "name": "AI is evolving fast", "articleId": "post-123", "voiceId": "12", "callbackURL": "https://your-site.com/wp-json/ats/v1/callback", }, }, ) print(response.status_code, response.text) # 202 and a plain text message ``` ### Immediate response `202 Accepted` with the plain text body: ```text Processing started. Results will be sent to the callback URL. ``` The `202` body is text, not JSON. Error responses are JSON, except `429`, which is plain text. ### Callback payload When generation finishes, Moknah sends a `POST` to your `callbackURL`: ```json { "articleId": "post-123", "response": { "audioFile": "https://api-storage.moknah.io/example/post-123.mp3", "srtFile": "https://api-storage.moknah.io/example/post-123.srt", "signature": "9f2c0c1e5b7a4d3e8f6a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60" } } ``` | Field | Description | | --- | --- | | `articleId` | The `articleId` you sent. | | `response.audioFile` | Public URL of the MP3, or `null` when generation failed. | | `response.srtFile` | Public URL of the SRT file, or `null` when generation failed. | | `response.signature` | HMAC-SHA256 signature of the payload, below. | A callback is also sent when generation produces no audio. Treat any callback whose `audioFile` or `srtFile` is `null` as a failure: do not mark the article as done, and send it again with `regenerate` set to `true`. #### Verifying the signature The signature is the HMAC-SHA256, as hex, of the string `articleId|audioFile|srtFile`, keyed with the SHA-256 hex digest of your API key. For a failed generation the string is `articleId|null|null`. ```python import hashlib import 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) ``` ```javascript 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 = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); ``` ### Idempotency and regeneration - Requests are keyed by `articleId` per company. A new `articleId` starts a new generation. - While an article is being generated, repeated requests for it return `409 ALREADY_PROCESSING`. - If an article was already generated and `regenerate` is `false`, the existing files are delivered to the callback again, with no new generation and no charge. - `regenerate` `true` forces a new generation for an existing `articleId`. - If an earlier attempt failed, sending the same `articleId` again generates it again. No new id is needed. ### Throughput Articles are generated from a queue in which every client gets a fair share. You can submit many articles at once: all are accepted, a few are generated at a time, and each is delivered as soon as it is ready. A large batch therefore completes gradually. The endpoint is rate limited per client IP address; requests above the limit get `429`. Current values are in [Limits](../limits/index.md). ### Billing Credits = characters of `text` multiplied by the rate of the preprocessing type (`2` costs more than `0`), with the Advanced engine multiplier for Advanced voices. Current rates are in [Pricing](../pricing/index.md). - Credits are taken only when a generation actually runs. - Delivering an already generated article again is free. - If generation or delivery fails, the credits are refunded automatically. ### Errors Error bodies are JSON of the form `{"code": "...", "error": "..."}`. | Status | Code | When | | --- | --- | --- | | 400 | `INVALID_VOICE_ID` | `voiceId` does not exist. | | 400 | `UNSUPPORTED_VOICE` | The voice is not of the key's voice type, or is not available right now. | | 401 | `AUTH_FAILED` | Missing `Authorization` header, invalid key, or a key without the Article to Speech service. | | 409 | `ALREADY_PROCESSING` | This article is being generated. Retry after it completes. | | 422 | `VALIDATION_ERROR` | Missing or blank `text`, missing or invalid `postData` fields, or text too short to narrate. | | 422 | `CONTENT_REJECTED` | The text was refused by the content policy check. | | 422 | `PROCESSING_ERROR` | Generation could not start or failed. Credits taken are refunded. | | 422 | `REFUND_FAILED` | Processing failed and the automatic refund did not complete. Contact api@moknah.io. | | 429 | (plain text) | Too many requests from this IP address. | --- # API key information and usage Section: Developer API URL: https://moknah.io/docs/md/api/key-and-usage.md Status: experimental > Read-only endpoints that describe the calling API key, its recent requests and its daily usage statistics. These endpoints exist and work with any active API key, but they are not part of the published OpenAPI schema. Treat their response fields as subject to change, and do not build critical logic on them. All three use `Authorization: Bearer YOUR_API_KEY`, take no body, and only ever describe the key that makes the call. ### Key information `GET https://moknah.io/api/v1/key/info/` Returns one JSON object: | Field | Description | | --- | --- | | `id`, `name`, `key_prefix` | Identity of the key. `key_prefix` is its first characters. | | `status` | `active`, `inactive`, `suspended` or `expired`. | | `engine` | Voice type of the key: `standard` or `advanced`. | | `allowed_services` | List of `tts`, `tts_ws`, `stt`, `stt_ws`. | | `credit_limit`, `credits_used`, `credits_remaining`, `usage_percentage` | The key's own credit cap and consumption. A `credit_limit` of `0` means no cap. | | `rate_limit_per_minute` | Requests per minute allowed for this key. | | `total_requests`, `last_used_at`, `expires_at`, `created_at` | Usage and lifetime. | `credits_remaining` here is what is left of the key's own cap. It is not the account's credit balance. ### Request log `GET https://moknah.io/api/v1/logs/` | Query parameter | Default | Description | | --- | --- | --- | | `limit` | 20 | Number of rows, at most 100. | | `offset` | 0 | Rows to skip. | Response: `{"count": , "results": [...]}`, newest first. Each row has `id`, `service`, `endpoint`, `method`, `status_code`, `response_time`, `credits_used`, `ip_address`, `error_message` and `created_at`. ### Daily statistics `GET https://moknah.io/api/v1/statistics/` | Query parameter | Default | Description | | --- | --- | --- | | `days` | 30 | How many days back to include. | Response: `{"period_days": , "results": [...]}`, newest first. Each row has `date`, `service`, `total_requests`, `successful_requests`, `failed_requests`, `success_rate`, `total_credits_used` and `avg_response_time`. ### Example ```bash curl "https://moknah.io/api/v1/key/info/" -H "Authorization: Bearer YOUR_API_KEY" curl "https://moknah.io/api/v1/logs/?limit=5" -H "Authorization: Bearer YOUR_API_KEY" curl "https://moknah.io/api/v1/statistics/?days=7" -H "Authorization: Bearer YOUR_API_KEY" ``` ### Credits These calls are free. --- # AI Connect (MCP) for developers Section: AI Connect (MCP) URL: https://moknah.io/docs/md/mcp/overview.md > Connect an MCP client to Moknah. Server address, transport, OAuth and bearer token authorization, scopes, plan gates, resources, prompts and the conventions every tool follows. ### Server | | | | --- | --- | | Address | `https://moknah.io/mcp` | | Transport | Streamable HTTP, stateless, JSON responses | | Authorization | OAuth 2.1 (authorization code with PKCE), or a bearer token issued by Moknah | | Acts as | The Moknah user who authorized the connection | The server is named "Moknah Audio Studio". It exposes tools, resources and prompts. ### Connect #### Clients with connector support Add a custom connector with the address `https://moknah.io/mcp` and sign in when asked. The client discovers the authorization server by itself and runs the OAuth flow in the browser. The step-by-step screens for each assistant are in the dashboard under **AI Assistant**. #### Bearer tokens Signing in with OAuth is the way users connect. The server also accepts a fixed bearer token in the `Authorization` header, for integrations that cannot run a browser sign-in. These tokens are not self-service: they are issued by Moknah for a specific account, on request to support@moknah.io. A client that needs a local bridge passes one like this: ```json { "mcpServers": { "moknah": { "command": "npx", "args": ["mcp-remote", "https://moknah.io/mcp", "--header", "Authorization: Bearer YOUR_MCP_TOKEN"] } } } ``` Only the hash of a token is stored. A token can be revoked and can carry an expiry date. ### Authorization details - Discovery: `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`. - Endpoints: `POST /oauth/register` (dynamic client registration), `/oauth/authorize` (sign-in and consent, PKCE `S256` required), `POST /oauth/token` (`authorization_code` and `refresh_token` grants). - A request without a valid token is answered `401` with a `WWW-Authenticate` header that points to the protected resource metadata, so a client can start the flow automatically. - Access tokens are opaque. There is no JWKS and nothing to verify locally. - An MCP token is not an API key. API keys (`mk_...`) are for the REST API and are not accepted by the MCP server. ### Scopes An issued token can be limited to groups of tools. A token with no scopes, which is what an OAuth sign-in produces by default, can call every tool. | Scope | Tools | | --- | --- | | `projects` | List, read, create and delete Audio Studio projects | | `authoring` | Chapters, lines, voice settings, AI review | | `voices` | List voices and play samples | | `generation` | Text to speech, rendering, jobs, audio and exports | | `cost` | Estimates and balance | A call outside the token's scopes fails with `SCOPE_DENIED`. The documentation tools are not scoped: every token can call them, because they return public information. ### Plan gates These tools work on every plan: `text_to_speech`, `list_voices`, `play_voice_sample`, `estimate_text_to_speech`, `check_credits`, `get_balance`, `get_job`, `get_job_result`, and all documentation tools. Every other tool belongs to Audio Studio and needs a plan that includes it. Without one the call fails with `UPGRADE_REQUIRED`, and the error carries the link to the plans page. See [Pricing](../pricing/index.md) for what each plan includes. ### Conventions #### Results and errors Every tool returns an object with `ok`. ```json {"ok": true, "project": {"id": 1234, "name": "My book"}} ``` ```json { "ok": false, "error": { "code": "INSUFFICIENT_CREDITS", "message": "Not enough credits for this operation: need 5400, balance 1200 (short 4200).", "details": {"required": 5400, "balance": 1200, "shortfall": 4200} } } ``` The error codes are listed in [Errors](../errors/index.md#mcp-tool-errors). #### Spending credits - Authoring is free: creating projects, editing text, reordering, voice settings and statuses cost nothing. - Tools that spend credits take `confirm_spend`. Called with `confirm_spend` false they return an estimate and spend nothing. Show the estimate to the user, and call again with `confirm_spend` true only after the user agrees. - A tool refuses to start work the balance cannot cover. #### Long work Rendering, document import and AI review run in the background. The tool returns a `job_ref` such as `project:1234`. Poll `get_job` about every 5 seconds until `is_terminal` is true, then call `get_job_result` for the URL of the output. #### Destructive tools `delete_project`, `delete_chapter` and `delete_line` need an explicit confirmation argument. Ask the user before passing it. #### Access rules - A tool acts only on the content of the signed-in user and their team. - Administrator privileges never apply over MCP. - Every call is recorded and visible to the user in the dashboard. ### Resources | URI | Content | | --- | --- | | `moknah://guide` | The [AI agent guide](../getting-started/ai-agents.md). Start here. | | `moknah://docs/index` | Index of this documentation. | | `moknah://docs/` | One document as Markdown, for example `moknah://docs/api/tts-generate`. Prices and limits are current. | | `moknah://docs/pricing`, `moknah://docs/limits`, `moknah://docs/errors` | Short forms of the pricing, limits and errors documents. | | `audio-studio://guide` | Index of the Audio Studio production references. | | `audio-studio://audiobook-production` | End-to-end document to audiobook workflow. | | `audio-studio://text-preparation` | Cleaning, verbalization and segmentation of text. | | `audio-studio://voice-settings` | What every voice parameter does, with safe ranges. | | `audio-studio://dialogue-and-pacing` | Speaker casting, pauses and line merging. | | `audio-studio://studio-reference` | Tool mechanics, options, review codes, jobs and limits. | Documentation resources have the MIME type `text/markdown`. ### Prompts | Prompt | Purpose | | --- | --- | | `get_started_with_moknah` | Find out what Moknah can do for a goal and take the first step. | | `integrate_text_to_speech` | Integrate text to speech into an application through the API. | | `narrate_document` | Turn a book or document into a finished audiobook. | | `debug_api_error` | Diagnose an API, WebSocket or MCP error. | | `choose_audio_service` | Pick the right service for a task. | | `review_chapter_qa` | Run AI review on a chapter and walk through the fixes. | | `set_up_voices` | Pick and apply voices for a project, then estimate the render. | ### Tools The full list is in [MCP tools](tools.md). --- # MCP tools Section: AI Connect (MCP) URL: https://moknah.io/docs/md/mcp/tools.md > Every tool of the Moknah MCP server by group, with what it does, whether it spends credits, and which plan it needs. The exact arguments of each tool are in the schema the server sends to the client. This page says what each tool is for. Legend: **Free** spends no credits. **Billable** spends credits, and only after `confirm_spend` is true. **Every plan** works without an Audio Studio plan; all other tools need a plan that includes Audio Studio. ### Documentation All free, read-only, every plan, and available to every token whatever its scopes. | Tool | Purpose | | --- | --- | | `search_docs` | Search this documentation in English or Arabic. Returns matching sections with a snippet, a relevance score and the slug for `read_doc`. Accepts API paths and error codes. | | `read_doc` | Read one document, or one section of it, as Markdown with current prices and limits. | | `list_docs` | List the documents, optionally by type or product. | | `get_product_info` | Everything about one product, with its current prices. | | `get_api_reference` | Reference of one REST or WebSocket endpoint, or the list of endpoints. | | `get_pricing_info` | Current prices in credits, text to speech multipliers, credit purchase prices and plans. | | `get_usage_limits` | Enforced limits: text length, rate limits, concurrency, file sizes, Audio Studio limits. | | `get_error_help` | Meaning, cause and fix of an error code, HTTP status or WebSocket close code. | | `get_workflow` | Step-by-step instructions for a common task, or the list of workflows. | ### Voices (`voices`) | Tool | Purpose | Notes | | --- | --- | --- | | `list_voices` | List the voices the user can use: their own, their team's and public ones. Each has an `engine` and `badges`. Pass `language` (for example `ar`) for names and badges in that language; voices without it fall back to English. | Free, every plan | | `play_voice_sample` | Show a player for a voice's sample clip so the user can hear it. | Free, every plan | ### Cost and balance (`cost`) All free and read-only. | Tool | Purpose | Notes | | --- | --- | --- | | `get_balance` | The user's credit balance. | Every plan | | `check_credits` | Whether a given number of credits is affordable. | Every plan | | `estimate_text_to_speech` | Credits to voice a text with a given voice and mode. | Every plan | | `estimate_project_generation` | Credits to render a project, all lines or only the changed ones. | | | `estimate_edits` | Credits to render only the edited and added lines of a project. | | | `estimate_book_cost` | Credits for a whole PDF book: OCR, optional normalization and translation, and speech. | | ### Speech and jobs (`generation`) | Tool | Purpose | Notes | | --- | --- | --- | | `text_to_speech` | Generate speech from text with no project. Returns a `job_ref`. | Billable, every plan | | `create_audiobook` | One call: create a project, set its voice, estimate, and start rendering if confirmed. | Billable | | `generate_audio` | Render a whole project or one chapter. `missing` renders only lines without audio, `all` renders everything again. | Billable | | `generate_lines` | Render specific lines by id. | Billable | | `transcribe_audio` | Transcribe an audio file to text. | Billable | | `get_job` | Poll a job until `is_terminal`. | Free, every plan | | `get_job_result` | The URL of a finished job's output. | Free, every plan | | `download_result` | Deprecated alias of `get_job_result`. | Free, every plan | | `get_line_audio` | URLs of the rendered audio of lines. | Free | | `get_chapter_audio` | URL of a chapter's merged audio. | Free | | `merge_chapters_audio` | Merge rendered chapters into one MP3. | Free | | `merge_chapters_subtitle` | Merge the chapters' subtitles into one SRT or VTT file. | Free | | `export_wav` | Export rendered audio as WAV, built in the background. | Free | | `play_audio`, `play_line` | Show or return audio for listening in the assistant. | Free | ### Projects (`projects`) | Tool | Purpose | Notes | | --- | --- | --- | | `list_projects` | The user's Audio Studio projects, newest first. | Free | | `get_project` | A project's overview: chapters with line and character counts, without line text. | Free | | `get_chapter` | One chapter with its lines. | Free | | `create_project` | Create a project from a document, from text, or empty. A document import returns a `job_ref`. | Free to create; OCR and other processing can be billable | | `delete_project` | Delete a project. Needs confirmation. | Free | ### Authoring (`authoring`) All free. A mode or voice set here affects what a later render costs. | Tool | Purpose | | --- | --- | | `add_chapter`, `rename_chapter`, `reorder_chapters`, `delete_chapter` | Manage chapters. Deleting needs confirmation. | | `add_line`, `add_lines`, `update_line`, `update_lines`, `reorder_lines`, `delete_line` | Manage lines. `add_lines` and `update_lines` are batch tools; use them instead of loops. Deleting needs confirmation. | | `set_project_voice` | Set a project's default voice, mode, context or content language. | | `set_line_voice_settings` | Override voice settings for one line. | | `set_line_qa_status` | Set a line's review status. | | `run_ai_qa` | AI review of a chapter's text or rendered audio. This one is billable. | | `get_qa_results` | Read the results of an AI review. | ### Using the tools well - Know the state first: `list_projects`, then `get_project`, then `get_chapter` only for the chapters you need. - Edit in batches with `update_lines`. - Never invent a voice id. Take it from `list_voices`, and let the user hear it with `play_voice_sample`. - Estimate before every billable call, show the estimate, and wait for the user's approval. - After a billable call, poll `get_job`, then confirm success with `get_job_result`. The complete procedure for a book is in [Create an audiobook](../workflows/audiobook.md). --- # Choose a service Section: Workflows URL: https://moknah.io/docs/md/workflows/choose-a-service.md > Decision guide that maps what a user wants to make to the right Moknah service and the way to reach it (web app, API or MCP). ### By goal | The user wants | Use | Reach it through | | --- | --- | --- | | A short voiceover or clip from text (up to 1,500 characters) | [Text to Speech](../products/text-to-speech.md) | Web app, REST API, MCP `text_to_speech` | | An audiobook, course or long narration from a document | [Audio Studio](../products/audio-studio.md) | Web app, MCP | | Speech in an app, generated on a server | [Generate speech API](../api/tts-generate.md) | REST API | | Speech with the lowest delay, for a chatbot or voice agent | [Stream speech API](../api/tts-stream.md) | WebSocket API | | Text from a recording, or subtitles | [Speech to Text](../products/speech-to-text.md) | Web app, REST API | | Live transcription from a microphone | [Stream transcription API](../api/stt-stream.md) | WebSocket API | | Exact timing for a text that already exists | Speech to Text, **Sync my text** | Web app | | Translated subtitles, or subtitles burned onto a video | Speech to Text, **Translate** and **Burn onto video** | Web app | | A video speaking another language | [Dubbing](../products/dubbing.md) | Web app | | A recording in a different voice, same words | [Voice Changer](../products/voice-changer.md) | Web app | | Their own voice for future narration | [Voice Cloning](../products/voice-cloning.md) | Web app, then use the voice anywhere | | Text translated | [Translation](../products/translation.md) | Web app | | An editable Word file from a PDF or a scan | [PDF to Word](../products/pdf-to-word.md) | Web app | | Audio on every article of a website | [Article to Speech](../products/article-studio.md) | WordPress plugin, callback API | | To do any of the above by asking an AI assistant | [AI Connect](../products/ai-connect.md) | MCP | ### Questions that settle the choice 1. **How long is the text?** Up to 1,500 characters: Text to Speech. Longer: Audio Studio, or split it yourself and send the parts through the API one after another. 2. **Does the audio have to start playing immediately?** Yes: the WebSocket stream. No: the REST endpoint, which returns a complete file. 3. **Is the source text or speech?** Text becomes speech (Text to Speech, Audio Studio, Article to Speech). Speech becomes text (Speech to Text) or a new voice track (Dubbing, Voice Changer). 4. **Should the words change?** Same words, new voice: Voice Changer. New language: Dubbing. New words: write them and use Text to Speech. 5. **Is the content Arabic?** Standard Arabic gains from Arabic Tashkeel. Dialects should use Basic processing and a voice that speaks the dialect. See [Languages](../platform/languages.md). 6. **Does it need to run without a person?** Then only the API and MCP capabilities apply: text to speech, speech to text, Article to Speech, and Audio Studio through MCP. The other tools need the web app. ### Things to say to the user before starting - The cost in credits, from the live estimate, before anything is generated. - Whether their plan includes the service. See [Pricing](../pricing/index.md). - The limits that apply to their file or text. See [Limits](../limits/index.md). - If a tool is web app only, say so instead of offering to run it. --- # Create an audiobook Section: Workflows URL: https://moknah.io/docs/md/workflows/audiobook.md > Turn a book or long document into a finished audiobook in Audio Studio, by hand in the web app or with an AI assistant over MCP, with the check that confirms each step. ### Before starting - The account needs a plan that includes Audio Studio. See [Pricing](../pricing/index.md). - Supported documents and limits: | Limit | Value | | --- | --- | | Characters per line | 1,500 | | Lines per chapter | 200 | | Chapters per project before an explicit confirmation is required | 500 | | Document types | doc, docx, pdf, epub, xlsx, xls, txt | | Document size | 50 MB | - Authoring is free. Credits are spent on OCR of scanned pages, optional AI text processing and translation, AI review, and rendering audio. ### In the web app 1. **Create the project.** Audio Studio, **New project**, add the document, choose how text is split into lines and the text processing (Basic, or AI-Enhanced for Standard Arabic). 2. **Check the text.** Open each chapter, fix what the import got wrong, keep lines between 3 and 20 words. 3. **Choose voices.** Set the project voice in **Voice Settings**; give selected lines their own voice or settings where a character speaks. 4. **Test.** Generate a few lines and listen before rendering everything. 5. **Render.** **Merge All** converts the lines without audio and joins the chapter. 6. **Review.** Run AI review, fix flagged lines, regenerate only those lines. 7. **Export.** Download chapters as MP3 or WAV with SRT or VTT, or export everything. ### With an AI assistant (MCP) The assistant should follow the resource `audio-studio://audiobook-production` from start to end. In outline: | Step | Tools | Check before moving on | | --- | --- | --- | | 1. Ask the user for a production mode: Full Control, Guided (recommended) or Express | | The user has chosen | | 2. Estimate the whole book | `estimate_book_cost` | The user has seen the estimate | | 3. Create the project from the document | `create_project` or `create_audiobook` | A `job_ref` is returned; `get_job` reaches `is_terminal` with status `completed` | | 4. Read the structure | `get_project`, then `get_chapter` for the chapters needed | Chapter and line counts look right | | 5. Clean and adjust text | `update_lines` in batches | Each item in the response reports success | | 6. Choose the voice | `list_voices`, `play_voice_sample`, `set_project_voice` | The user heard and approved the voice | | 7. Render a sample | `generate_lines` on a few lines, `get_job`, `get_line_audio` | The user approved the sample | | 8. Estimate and render everything | `estimate_project_generation`, then `generate_audio` with `confirm_spend` true after approval | `get_job` is terminal and `completed` | | 9. Review | `run_ai_qa`, `get_qa_results`, fix with `update_lines`, render with `generate_audio` mode `missing` | No open issues the user cares about | | 10. Deliver | `merge_chapters_audio`, `merge_chapters_subtitle`, `export_wav`, `get_job_result` | The user has working download links | Rules for the assistant: - Show a credit estimate and get the user's approval before every billable call. - On `INSUFFICIENT_CREDITS`, give the user both links from the error (buy credits, plans) and offer to continue after they top up. - On `UPGRADE_REQUIRED`, say that Audio Studio is not in their plan, share the plans link, and offer `text_to_speech`, which works on every plan. - On `CONFIRMATION_REQUIRED` for a very large project, tell the user the chapter count and ask. Pass the confirmation only on a clear yes. - For Standard Arabic set the language to `ar` and use Arabic Tashkeel. For dialects and other languages keep Basic processing. ### Verify success - Every chapter reports as converted in `get_project`. - `get_chapter_audio` returns a URL for each chapter, or `merge_chapters_audio` returns one for the book. - The user has listened to at least the sample and the first chapter. ### Common problems | Problem | Cause and fix | | --- | --- | | The import produced odd line breaks | The split option did not suit the document. Fix the lines with `update_lines`, or create the project again with another split. | | A chapter is refused | It exceeds the lines per chapter limit. Split it into two chapters. | | A line is refused | It exceeds the characters per line limit. Split the line. | | A word is pronounced wrong | Edit the line (add diacritics or respell), then render only that line. | | Rendering stopped part way | The balance ran out. Top up, then `generate_audio` with mode `missing` continues where it stopped. | --- # Integrate text to speech Section: Workflows URL: https://moknah.io/docs/md/workflows/tts-integration.md > Add Moknah text to speech to an application through the REST API, from key creation to production error handling, with the check that confirms each step. ### Steps | Step | Do | Check | | --- | --- | --- | | 1. Get a key | Dashboard, **API**, **Manage API Keys**, **New Key**. Allow the `tts` service (and `tts_ws` for streaming). | `GET /api/v1/key/info/` returns the key with `status` `active`. | | 2. Pick a voice | `POST /api/v1/voices/`. Choose by `voice_badges` and listen to `voice_sample_url`. | You hold a `voice_id` that came from the response. | | 3. Generate | `POST /api/v1/tts/generate/` with `text`, `voice_id` and, for Arabic, `language`. | Status `200` and a `Content-Type` starting with `audio/`. | | 4. Handle errors | Branch on the status code, below. | Each error path is exercised once. | | 5. Respect limits | Send one request at a time and stay under the per-minute limits. | No `429` responses in normal operation. | ### Choosing the endpoint - A complete file per request: [Generate speech (REST)](../api/tts-generate.md). - Audio that starts playing while the text is still arriving, such as LLM output: [Stream speech (WebSocket)](../api/tts-stream.md). ### Text longer than the limit The REST endpoint takes up to 1,500 characters per request. For longer text: 1. Split at sentence boundaries into parts under the limit. 2. Send the parts one after another, never in parallel. 3. Join the audio in order. With `pcm_*` or `wav_*` output the parts concatenate cleanly; MP3 parts can be joined with an audio tool. For whole books, Audio Studio does the splitting, voicing, review and merging; an assistant can drive it through [MCP](../mcp/overview.md). ### A production client ```python import time import requests API = "https://moknah.io/api/v1" class MoknahTTS: def __init__(self, api_key): self.session = requests.Session() self.session.headers["Authorization"] = f"Bearer {api_key}" def speak(self, text, voice_id, language=None, max_attempts=5, **settings): body = {"text": text, "voice_id": voice_id} if language: body["language"] = language if settings: body["voice_settings"] = settings for attempt in range(max_attempts): response = self.session.post(f"{API}/tts/generate/", json=body, timeout=180) if response.status_code == 200: return response.content if response.status_code == 429: wait = int(response.headers.get("Retry-After", 0)) or 2 ** attempt time.sleep(wait) continue if response.status_code >= 500: time.sleep(2 ** attempt) continue raise RuntimeError(f"{response.status_code}: {response.text}") raise RuntimeError("Gave up after repeated 429 or 5xx responses") tts = MoknahTTS("YOUR_API_KEY") audio = tts.speak("مرحبا بك في منصة مكنة", voice_id=1328, language="ar", mode="emotion") with open("speech.mp3", "wb") as f: f.write(audio) ``` Call `speak` from one worker at a time per account, for example behind a queue. ### Error handling | Status | Meaning | What to do | | --- | --- | --- | | 400 | Invalid field | Fix the request. `error.details` names the field. Do not retry unchanged. | | 401 | Key problem | Check the key, its status, and the IP allowlist. Do not retry. | | 402 | Not enough credits, or the key's credit cap is reached | Top up or raise the cap. Do not retry until then. | | 403 | The key may not use this service | Allow the service on the key. | | 422 | Text refused by the content check | Do not retry the same text. | | 429 | Another request is running, or a per-minute limit is reached | Wait (`Retry-After` when present, otherwise back off) and retry. | | 500 | Generation failed | Retry with backoff. If it persists, send `error.details.request_id` to support. | Details of each code are in [Errors](../errors/index.md). ### Cost control - Estimate before sending: characters multiplied by the current rate and multiplier in [Pricing](../pricing/index.md). - `quality` and `studio` modes, Arabic Tashkeel, AI Poet and voices with a fee cost more than the basic case. - Give each integration its own key with a credit limit, so a bug cannot spend the whole balance. ### Security Keep the key on your server. Do not ship it in a web page or a mobile app; proxy the request through your backend. --- # Make subtitles for a video Section: Workflows URL: https://moknah.io/docs/md/workflows/subtitles.md > Get subtitles from a video or audio file, translate them and burn them onto the video in the web app, or get a transcript through the API. ### In the web app: transcribe, translate and burn in one job | Step | Do | Check | | --- | --- | --- | | 1 | Open **Speech to Text**, click **New**, choose **Speech to text**. If you already have the exact script, choose **Sync my text** and paste it. | The right start is selected. | | 2 | Switch on **Translate** and choose the language, and switch on **Burn onto video** if wanted. | The summary lists the steps and the estimated credits. | | 3 | Upload the file and choose the exact spoken language and region. | The file is within the size limit. | | 4 | Choose the line style: **Standard**, or **Word level** for short-form video. | | | 5 | Click **Start** and wait on the job page. | The subtitle preview appears. | | 6 | Review the translated lines next to the original and save any corrections. | The corrected text shows in the preview. | | 7 | Choose the video, pick the subtitles to burn, style them, and burn. | The video downloads and plays with subtitles. | Download the subtitled video promptly: the video and its subtitled copy are deleted right after use, or after 10 minutes at most. The SRT files stay with the job. ### Through the API: transcript only 1. `POST /api/v1/stt/submit/` with the audio file, the `language` and `output_format` `srt` or `json`. 2. Poll `GET /api/v1/stt/status/{job_id}/` every few seconds. 3. With `srt`, the finished response is the SRT file. With `json`, read `result.subtitles`. See [Transcribe speech](../api/stt-transcribe.md). The API takes audio files; extract the sound track from a video first. Translating subtitles and burning them are web app steps and are not available through the API. ### Which tool for which need - Subtitles in the same language: Speech to text. - Subtitles in another language: Speech to text with Translate. - A spoken version in another language: [Dubbing](../products/dubbing.md). - You already have an SRT or VTT file: start with **My subtitle file** to translate or burn it; that start is free. ### Cost Transcription and text sync are charged per minute of audio, translation by the length of the subtitles, and burning is free. Rates are in [Pricing](../pricing/index.md). --- # Build a real-time voice agent Section: Workflows URL: https://moknah.io/docs/md/workflows/realtime-voice-agent.md > Connect streaming speech to text, your own language model and streaming text to speech into a conversational voice agent. Architecture, audio formats, turn-taking and pitfalls. ### Architecture ```text microphone --16 kHz PCM--> wss /api/v1/stt/ws/ --final text--> your LLM speaker <--PCM audio--- wss /api/v1/tts/ws/ <--reply text--- your LLM ``` Moknah provides the two streams. The language model is yours. ### Requirements - An API key that allows `stt_ws` and `tts_ws`. - Credits: speech to text is prepaid by the minute, text to speech is charged per character as text is sent. - One open stream per account for each of the two services. ### Steps | Step | Do | Check | | --- | --- | --- | | 1 | Open the speech to text stream with `?language=` set to the caller's language and region. | You receive `{"status": "connected", ...}`. | | 2 | Send microphone audio as raw 16 kHz, 16-bit, mono PCM frames of about 100 ms. | `partial` messages arrive while someone is speaking. | | 3 | On each `final` message with non-empty text, send the text to your LLM. | | | 4 | Open the text to speech stream, send `init` with a `voice_id` and `output_format` `pcm_24000`, and wait for `ready`. | You receive `{"status": "ready", ...}`. | | 5 | Send the reply as `text` messages, sentence by sentence as the LLM produces them, then `stop`. | Binary audio frames arrive. | | 6 | Play the frames as 24 kHz, 16-bit, mono PCM. Stop at `end_of_stream`. | The reply is heard completely. | | 7 | While the agent is speaking, do not forward microphone audio, or the agent will hear itself. | No echo loops. | ### Minimal agent ```python # pip install websockets pyaudio import asyncio import json import pyaudio import websockets API_KEY = "YOUR_API_KEY" HEADERS = {"Authorization": f"Bearer {API_KEY}"} STT_URL = "wss://moknah.io/api/v1/stt/ws/?language=ar-SA" TTS_URL = "wss://moknah.io/api/v1/tts/ws/" VOICE_ID = 1710 # use an id from your own voice list audio = pyaudio.PyAudio() microphone = audio.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True, frames_per_buffer=1600) speaker = audio.open(format=pyaudio.paInt16, channels=1, rate=24000, output=True) speaking = False async def call_llm(text): return f"سمعتك تقول: {text}" # replace with your model async def speak(text): global speaking speaking = True loop = asyncio.get_running_loop() try: async with websockets.connect(TTS_URL, additional_headers=HEADERS) as tts: await tts.send(json.dumps({"type": "init", "voice_id": VOICE_ID, "output_format": "pcm_24000"})) while json.loads(await tts.recv()).get("status") != "ready": pass await tts.send(json.dumps({"type": "text", "data": text})) await tts.send(json.dumps({"type": "stop"})) async for message in tts: if isinstance(message, bytes): await loop.run_in_executor(None, speaker.write, message) elif json.loads(message).get("type") == "end_of_stream": break finally: speaking = False async def send_microphone(stt): loop = asyncio.get_running_loop() while True: frame = await loop.run_in_executor(None, microphone.read, 1600, False) if not speaking: await stt.send(frame) async def handle_results(stt): async for message in stt: data = json.loads(message) if data.get("type") == "final" and data["text"].strip(): await speak(await call_llm(data["text"])) async def main(): async with websockets.connect(STT_URL, additional_headers=HEADERS) as stt: await asyncio.gather(send_microphone(stt), handle_results(stt)) asyncio.run(main()) ``` ### Latency - Use `pcm_24000` for playback; there is nothing to decode. - End each text chunk with sentence punctuation so audio starts at once. - Keep the default `emotion` mode, or set `fast_mode` for the low-latency model. - Open the text to speech stream before the LLM answers if every millisecond counts, and send text as it arrives. ### Pitfalls | Symptom | Cause | Fix | | --- | --- | --- | | Close code `4290` | A stream of the same service is already open for the account | Close the previous stream first, and wait about 15 seconds after a crash. | | Empty or nonsense transcripts | The audio is not raw 16 kHz mono 16-bit PCM | Convert before sending. Do not send MP3 or a WAV header. | | Close code `4009` | An audio frame was too large | Send frames of about 100 ms. | | The agent answers itself | Microphone audio was forwarded while the agent spoke | Pause forwarding during playback. | | Close code `4002` during a call | Credits ran out | Check the balance before starting long sessions. | Message formats and every close code are in [Stream transcription](../api/stt-stream.md) and [Stream speech](../api/tts-stream.md). --- # Add audio to website articles Section: Workflows URL: https://moknah.io/docs/md/workflows/article-audio.md > Give every article of a site a spoken version with the WordPress plugin or the Article to Speech callback API, and handle callbacks, retries and updates correctly. ### Choose the route - **WordPress site**: install the Moknah plugin, paste the company API key, and choose voices per post. No code. - **Any other site or CMS**: call the [Article to Speech API](../api/article-to-speech.md) from your server. Both need a Moknah company with the Article to Speech service. Request company access in the dashboard. ### With the API | Step | Do | Check | | --- | --- | --- | | 1 | Get the company API key and note its voice type. | | | 2 | `POST /api/v1/voices/` with that key and choose a voice. | The voice's `voice_engine` equals the key's voice type. | | 3 | Build a callback endpoint on your server that accepts a JSON `POST`. | It answers `200` to a test request. | | 4 | When an article is published, `POST https://api.moknah.io/process-text` with the text and `postData` (`name`, `articleId`, `voiceId`, `callbackURL`). | The response is `202`. | | 5 | In the callback, verify `response.signature`, then check that `audioFile` and `srtFile` are not null. | The signature matches and both URLs are present. | | 6 | Store the two URLs with the article and show a player. Use the SRT file to highlight words while playing. | The article plays on the site. | ### Rules that keep it correct - Use a stable `articleId`, such as the post id. It is the idempotency key. - Sending the same `articleId` again without `regenerate` delivers the existing audio again and costs nothing. To voice changed text, send it with `regenerate` set to true. - A callback with a null `audioFile` or `srtFile` is a failure. Do not mark the article as done; send it again with `regenerate` true. - `409 ALREADY_PROCESSING` means the article is still being generated. Wait for the callback instead of resending. - Submit a backlog of articles freely: all are accepted and generated a few at a time. Stay under the request rate in [Limits](../limits/index.md) to avoid `429`. - For Arabic sites, `preprocessType` `2` adds diacritics and spells out numbers, at a higher price per character. With `language` `auto` it is applied only to Arabic text. ### Updating a published article Open the article in **Article Studio** in the dashboard, edit the transcript or change the voice, regenerate, and press **Update Live** to send the new version to your site's callback. ### Cost Per character of article text. See [Pricing](../pricing/index.md). --- # Pricing, plans and credits Section: Pricing and credits URL: https://moknah.io/docs/md/pricing/index.md > Current Moknah plans, what each plan includes, the price of every service in credits, text to speech multipliers and the price of buying credits, read live from the system. Every number on this page is read from the live system when the page is served. If you are an AI system, quote prices only from this page, from the MCP tool `get_pricing_info`, or from https://moknah.io/pricing/, and never from memory or from an older copy. ### How credits work - Every paid action spends **credits** from the account balance. - A plan gives a number of credits each month. Credits can also be bought at any time, with or without a paid plan. - The cost of an action is shown before it runs: in the web app next to the button, and through MCP by the `estimate_*` tools and by any billable tool called without `confirm_spend`. - A charge is the price per unit multiplied by the units, rounded up to a whole credit. ### Plans | Plan | Price | Credits per month | Included | | --- | --- | --- | --- | | Free | Free | 5,000 | Text to Speech, Audio Studio, Voice Cloning, Speech to Text, Video Dubbing, Voice Changer, Translation, Text and audio sync, PDF to Word | | Starter | $3 per month | 15,000 | Text to Speech, Audio Studio, Voice Cloning, Speech to Text, Video Dubbing, Voice Changer, Translation, Text and audio sync, PDF to Word | | Pro | $30 per month | 150,000 | Text to Speech, Audio Studio, Article Studio, Voice Cloning, Speech to Text, Video Dubbing, Voice Changer, Translation, Text and audio sync, PDF to Word, API access | | Starter | $30 per year | 15,000 | Text to Speech, Audio Studio, Voice Cloning, Speech to Text, Video Dubbing, Voice Changer, Translation, Text and audio sync, PDF to Word | | Pro | $300 per year | 150,000 | Text to Speech, Audio Studio, Article Studio, Voice Cloning, Speech to Text, Video Dubbing, Voice Changer, Translation, Text and audio sync, PDF to Word, API access | The "Included" column lists the tools of each plan. A tool that is not listed for a plan is not available on it. Enterprise plans with custom volumes, limits and terms are arranged with sales@moknah.io. ### Buying credits | Buying credits | Value | | --- | --- | | Price of 1,000 credits | $0.25 | | Price of 1,000 credits for Pro subscribers | $0.2 | | Purchased credits expire after | 365 days | ### Price of each service | Service | Credits | Per | Used by | | --- | --- | --- | --- | | Text to speech, Basic text processing (`prerecording` 1) | 1 | character | Text to Speech page, Audio Studio, REST API | | Text to speech with Arabic Tashkeel (`prerecording` 2) | 2 | character | Text to Speech page, Audio Studio, REST API | | Text to speech with AI Poet (`prerecording` 3) | 2 | character | Text to Speech page, Audio Studio, REST API | | Streaming text to speech | 1 | character | WebSocket API | | Speech to text (transcription) | 500 | minute of audio | Speech to Text, REST API | | Streaming speech to text | 500 | minute of audio | WebSocket API | | Sync my text (text and audio sync) | 137.5 | minute of audio | Speech to Text | | Subtitle translation | 1.25 | character | Speech to Text | | Text translation | 0.1 | character | Translation page | | Project translation | 0.1 | character | Audio Studio | | AI text normalization | 2 | character | Audio Studio | | AI text review | 2 | character | Audio Studio | | AI audio review | 3 | character | Audio Studio | | PDF OCR | 200 | page | PDF to Word, document import in Audio Studio | | Dubbing | 1000 | second of media | Dubbing | | Voice Changer, fee per job | 125 | job | Voice Changer | | Voice Changer, per second of audio | 125 | second of audio | Voice Changer | | Article video recording | 100 | job | Article Studio | A charge is the credits per unit multiplied by the units, rounded up to a whole credit. Free: burning subtitles onto a video, bringing your own SRT or VTT file, and all Audio Studio authoring (creating, editing, reordering, voice settings). ### How text to speech credits are calculated `credits = characters x (rate of the text processing mode + voice fee) x multiplier`, rounded up. 1. **Rate of the text processing mode.** Basic, Arabic Tashkeel and AI Poet each have a rate per character in the table above. Streaming has its own rate. 2. **Voice fee.** Most voices have no fee. A voice with a fee (`voice_fees` above zero in the voice list) adds a surcharge per character that depends on the account's plan. The estimate shown before generating includes it. 3. **Multiplier.** It depends on the Standard engine mode, or on the engine: | Voice engine and mode | Credit multiplier | | --- | --- | | Standard engine, `emotion` mode (default) | x1 | | Standard engine, `quality` mode | x2 | | Standard engine, `studio` mode | x2 | | Advanced engine voices | x1.5 | Worked example of the method, without a voice fee: a text of 500 characters costs 500 times the Basic rate in `emotion` mode; the same text in a mode with a higher multiplier costs that amount times the multiplier. ### How speech to text credits are calculated - A file is charged per minute of audio, in proportion to its duration, when the job is accepted. A failed job is refunded. - A live stream is prepaid one minute at a time; the unused part of the last minute is returned when the stream closes. ### Refunds for failed work - REST text to speech: when generation fails after the charge, a refund request is created automatically and reviewed by the Moknah team. - REST speech to text: a failed job is refunded automatically. - Article to Speech: a failed generation or delivery is refunded automatically. - Streaming text to speech: credits for text that produced no audio go into a refund request automatically. ### Purchased credits Credits that are bought can expire; the period is in the table under [Buying credits](#buying-credits). ### Not listed here Promotions and discounts, taxes, and enterprise terms are not covered by this page. For those, see https://moknah.io/pricing/ or ask sales@moknah.io. --- # Limits Section: Limits URL: https://moknah.io/docs/md/limits/index.md > Current limits of the Moknah API, Audio Studio and file uploads (text length, requests and credits per minute, concurrency, file sizes), and what happens when one is reached. The tables on this page are read from the code that enforces the limits when the page is served. ### API limits | Limit | Value | | --- | --- | | REST text to speech, characters per request | 1,500 | | Streaming text to speech, characters per text chunk | 2,000 | | REST speech to text, audio file size | 50 MB | | Streaming speech to text, audio chunk size | 256,000 bytes | | Requests per minute (default for a new API key) | 60 | | Credits per minute (default for a new API key) | 10,000 | | REST text to speech requests in progress per account | 1 | | Open streams per account, per streaming service | 1 | | Article to Speech requests per client IP | 100 per minute | | Article to Speech articles generating at once per company | 2 | Notes: - Requests per minute and credits per minute are settings of each API key. The values above are the defaults of a new key. To raise them, write to sales@moknah.io. - Both per-minute limits are counted per account, across all of its keys. - Credits per minute applies to the REST endpoints. A request that would pass the limit is refused before any work is done. - An API key can also have a total credit limit of its own; when it is reached the key stops working. #### One request at a time - REST text to speech runs one request per account at a time. A second request sent while one is running gets `429 CONCURRENT_REQUEST`. - Each streaming service allows one open stream per account. A second connection is closed with code `4290`. - After a stream ends unexpectedly, wait about 15 seconds before reconnecting. For many short texts in a row, open one text to speech stream and send them over it. The stream is not subject to the requests per minute limit. #### When a limit is reached over REST The response is `429` with these headers: | Header | Meaning | | --- | --- | | `Retry-After` | Seconds to wait before retrying. | | `RateLimit-Reset` | Unix time when the limit resets. | A `402` for insufficient credits carries `Moknah-Credits-Remaining` and `Moknah-Credits-Used`. Successful responses carry no rate limit headers. #### Retrying Retry `429` and `5xx` responses with exponential backoff: wait the `Retry-After` value when present, otherwise 1, 2, 4, 8 seconds. Do not retry `400`, `401`, `402`, `403` or `422` without changing something. ### Audio Studio limits | Limit | Value | | --- | --- | | Characters per line | 1,500 | | Lines per chapter | 200 | | Chapters per project before an explicit confirmation is required | 500 | | Document types | doc, docx, pdf, epub, xlsx, xls, txt | | Document size | 50 MB | A document import splits chapters that are too long automatically. Through MCP, `update_lines` accepts up to 200 edits per call. ### Upload limits | Limit | Value | | --- | --- | | Speech to Text, audio file | 50 MB | | Speech to Text, video file | 200 MB | | Speech to Text, subtitle file (SRT or VTT) | 2 MB | | Voice Cloning, recordings per voice | 1 to 5 | | Voice Cloning, size per recording | 50 MB | | Voice Cloning, an unused clone is deleted after | 7 days | | Voice Changer, audio file | 50 MB | | Dubbing, video or audio file | 100 MB | | PDF to Word, PDF file | 50 MB | ### Text to speech formats - MP3: `mp3_22050_32`, `mp3_24000_48`, `mp3_44100_32`, `mp3_44100_64`, `mp3_44100_96`, `mp3_44100_128`, `mp3_44100_192` - PCM (raw 16-bit little-endian mono, no header): `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_32000`, `pcm_44100`, `pcm_48000` - Opus (Ogg container): `opus_48000_32`, `opus_48000_64`, `opus_48000_96`, `opus_48000_128`, `opus_48000_192` - WAV (16-bit mono, REST only): `wav_16000`, `wav_22050`, `wav_24000`, `wav_44100`, `wav_48000` Default for REST: `mp3_44100_128`. Default for streaming: `pcm_24000`. ### Limits that depend on the plan - Which tools an account can use, and its monthly credits: see [Pricing](../pricing/index.md). - How many voices an account can clone: shown on the clone page of the web app. --- # Errors Section: Errors URL: https://moknah.io/docs/md/errors/index.md > Every error of the Moknah REST API, the WebSocket streams, the Article to Speech API and the MCP tools, with its cause and the fix. ### Error formats REST errors raised by endpoint logic: ```json {"success": false, "error": {"code": "ERROR_CODE", "message": "What went wrong", "details": {}}} ``` `details` appears only when there is more to say. Three framework-level errors are flat instead: `authentication_failed` (401), the 403 for a key without access to a service, and `method_not_allowed` (405). WebSocket errors are either a JSON text frame `{"error": "message"}` or a close code. Article to Speech errors are `{"code": "ERROR_CODE", "error": "message"}`. MCP tool errors are `{"ok": false, "error": {"code": "ERROR_CODE", "message": "...", "details": {}}}`. ### REST API errors #### `INVALID_REQUEST` (HTTP 400) A field is missing, has the wrong type or an unsupported value. `error.details` maps each field to its problem. Common causes: missing `text` or `voice_id`; text longer than 1,500 characters; a `voice_id` that does not exist, is not available to the account, or belongs to the other voice type than the key; an unknown key inside `voice_settings`; an invalid `mode`, `style`, `pace` or `output_format`; `prerecording` 2 or 3 with a language other than Arabic; an unknown `language` code; for the voice list, an `engine` that is not the key's voice type. Fix the request. Retrying it unchanged gives the same error. #### `INVALID_AUDIO` (HTTP 400) The file sent to `POST /api/v1/stt/submit/` could not be read as audio. Send a standard audio file such as MP3, WAV or M4A. #### `authentication_failed` (HTTP 401) ```json {"error": "authentication_failed", "message": "Authentication required. Provide a valid API key or the ip address isn not allowed."} ``` Causes: no `Authorization: Bearer` header; a key that does not exist; a key that is revoked, inactive, expired or over its own credit limit; a deactivated account; a request from an address outside the key's IP allowlist. Check the key in the dashboard under **API**, **Manage API Keys**. The body does not say which cause applies. #### `INSUFFICIENT_CREDITS` (HTTP 402) The account balance does not cover the request. For text to speech, `error.details` has `credits_remaining` and `credits_used` (the credits the request needs), and the response has the headers `Moknah-Credits-Remaining` and `Moknah-Credits-Used`. Buy credits or move to a larger plan, then retry. See [Pricing](../pricing/index.md). #### `CREDIT_LIMIT_EXCEEDED` (HTTP 402) The API key has its own total credit limit and this request would pass it. The account may still have credits. Raise the key's credit limit, or use another key. #### Forbidden: no service access (HTTP 403) ```json {"detail": "API key does not have access to this service."} ``` The key's allowed services do not include the one called (`tts`, `tts_ws`, `stt`, `stt_ws`). Edit the key and allow the service. #### `JOB_NOT_FOUND` (HTTP 404) `GET /api/v1/stt/status/{job_id}/` was called with an id that does not exist or belongs to another key. Use the `job_id` returned by the submit call, with the same key. #### `method_not_allowed` (HTTP 405) The endpoint was called with the wrong HTTP method. `POST /api/v1/voices/` and `POST /api/v1/tts/generate/` are POST; the job status and key endpoints are GET. #### `CONTENT_REJECTED` (HTTP 422) The text was refused by the automatic content policy check. Do not retry the same text. The content policy is at https://moknah.io/content-policy/. #### `CONCURRENT_REQUEST` (HTTP 429) Another text to speech REST request of the same account is still running. Requests run one at a time per account. Wait for the first response, then send the next request. Queue requests on your side. #### `RATE_LIMIT_EXCEEDED` (HTTP 429) The requests per minute or credits per minute limit was reached. The response has `Retry-After` (seconds) and `RateLimit-Reset`, and `error.details` has `reset_after`. Wait, then retry. Current limits are in [Limits](../limits/index.md); sales@moknah.io can raise them. #### `JOB_FAILED` (HTTP 500) A speech to text job failed while processing. The credits taken for it are refunded automatically. Submit the file again; if it fails again, check that the file is valid audio. #### `INTERNAL_SERVER_ERROR` (HTTP 500) Something failed on Moknah's side. For text to speech, `error.details.request_id` identifies the request. Retry with backoff. If it persists, send the `request_id` to support@moknah.io. When the request was charged, a refund request is created automatically. #### Generation error codes (HTTP 500) Text to speech can also answer `500` with the code `tts_generation_error` or `audio_processing_error` when the voice engine failed. Treat them like `INTERNAL_SERVER_ERROR`: retry with backoff. ### WebSocket close codes #### Close code 1000 Normal end of a stream. #### Close code 3011 Text to speech stream only. Audio generation failed. An `{"error": "Audio generation failed. Please try again."}` frame is sent first. Open a new stream and send the text again. #### Close code 4001 No API key was sent. Add `Authorization: Bearer YOUR_API_KEY` to the handshake, or `?api_key=` in the URL. #### Close code 4002 Authentication failed, or credits are insufficient. An error frame sent just before the close says which: invalid or inactive key, a key without `tts_ws` or `stt_ws` access, an IP address that is not allowed, no credits to start, or for speech to text no credits to continue. #### Close code 4009 Speech to text stream only. An audio frame was larger than 256,000 bytes. Send frames of about 100 ms. #### Close code 4290 The account already has an open stream of this service. One stream per account and service is allowed. Close the other stream; after a crash, wait about 15 seconds for the lock to clear. #### Stream error messages Errors that arrive as `{"error": "..."}` frames, such as `Chunk too large. Maximum 2000 characters per chunk.`, `Not initialized. Send init message first.` and `Insufficient credits during stream`, are listed with their causes in [Stream speech](../api/tts-stream.md#messages-you-receive) and [Stream transcription](../api/stt-stream.md#close-codes). ### Article to Speech errors #### `AUTH_FAILED` (HTTP 401) The `Authorization` header is missing, the company API key is invalid, or the key's company does not have the Article to Speech service. This endpoint needs the company key, not a dashboard API key. #### `VALIDATION_ERROR` (HTTP 422) `text` is missing or blank, a `postData` field is missing or invalid, the text is too short to narrate, or `preprocessType` 2 was sent with a language other than Arabic. The `error` text names the field. #### `INVALID_VOICE_ID` (HTTP 400) `voiceId` does not exist. Take the id from the voice list. #### `UNSUPPORTED_VOICE` (HTTP 400) The voice is not of the company key's voice type (Standard or Advanced), or it is not available right now. Choose a voice whose `voice_engine` equals the key's type. #### `ALREADY_PROCESSING` (HTTP 409) This `articleId` is being generated right now. Wait for the callback instead of sending it again. #### `PROCESSING_ERROR` (HTTP 422) Generation could not start or failed. Credits taken are refunded. Send the article again later. #### `REFUND_FAILED` (HTTP 422) Processing failed and the automatic refund did not complete. Contact api@moknah.io with the `articleId`. #### Too many requests to Article to Speech (HTTP 429) More requests came from one IP address than the limit allows. The body is plain text. Space out the requests; see [Limits](../limits/index.md). ### MCP tool errors #### `UNAUTHENTICATED` The MCP token is missing, invalid, revoked or expired. Connect again. #### `FORBIDDEN` The signed-in user may not act on this item, or the chosen voice is not in their plan. An assistant can only reach the user's own and team content. #### `NOT_FOUND` The project, chapter, line, voice, job or document does not exist or is not visible to the user. For documentation tools, `error.details.suggestions` lists valid values. #### `INVALID_INPUT` An argument failed validation, for example a chapter with more lines than allowed, a line that is too long, or a destructive tool called without its confirmation argument. The message says what to change. #### `INSUFFICIENT_CREDITS` (MCP) The balance does not cover the work. `error.details` has `required`, `balance`, `shortfall`, `buy_credits_url` and `subscribe_url`. Give the user both links and offer to continue after they top up. #### `UPGRADE_REQUIRED` The tool belongs to Audio Studio and the user's plan does not include it. `error.details.subscribe_url` is the plans page. `text_to_speech` still works on every plan. #### `SCOPE_DENIED` The token is limited to some groups of tools and this tool is not among them. #### `CONFIRMATION_REQUIRED` The action needs the user's explicit agreement, for example creating a very large project. Ask the user, and call again with the confirmation argument only on a clear yes. #### `RATE_LIMITED` Too many calls in a short time. Wait and retry. #### `NOT_IMPLEMENTED` The capability is not available through MCP. #### `INTERNAL` An unexpected failure. `error.details.request_id` identifies the call. Retry once; if it fails again, give the user the `request_id` for support@moknah.io. ### How to handle errors in code | Status | Retry? | Action | | --- | --- | --- | | 400, 422 | No | Fix the request. | | 401, 403 | No | Fix the key or its permissions. | | 402 | No | Add credits or raise the key's credit limit. | | 404, 405 | No | Fix the URL, the id or the method. | | 409 (Article to Speech) | Later | Wait for the callback. | | 429 | Yes | Wait `Retry-After`, or back off: 1, 2, 4, 8 seconds. | | 500 | Yes | Back off; report the `request_id` if it persists. | --- # Security and privacy Section: Security URL: https://moknah.io/docs/md/security/index.md > How API keys and MCP tokens are protected, what an AI assistant can reach, how content is moderated, and what users should know about their data. ### API keys - A key is shown once, when it is created. Moknah stores only a SHA-256 hash and the first characters for identification, so a lost key cannot be recovered; create a new one. - A key can be limited to chosen services, to a total number of credits, to a list of IP addresses, and to an expiry date. - A key can be revoked at any time in the dashboard. A revoked, expired or over-limit key is refused at once. - When an account is deactivated, all of its keys stop working. Practices to follow: - Keep keys on a server. Never place one in a web page, a mobile app or a public repository. - Use one key per integration, with a credit limit, so a leak or a bug has a bounded cost. - Prefer the `Authorization` header. The `?api_key=` form for WebSockets puts the key in a URL. - Rotate a key that may have been exposed: create a new one, switch, revoke the old one. ### MCP connections - An assistant is authorized with OAuth 2.1 and PKCE: the user signs in to Moknah and approves the connection. The assistant never sees the password. - Tokens are stored as hashes. - An assistant acts as the user who authorized it and can reach only that user's content and their team's. - Administrator privileges are removed for every MCP call, even when the user is an administrator. - Deleting needs an explicit confirmation, and spending needs an explicit approval. - Every tool call is recorded with the tool, its arguments in shortened form, the credits estimated and charged, and the result. Users see their own calls under **AI Assistant**, **Activity**. ### Callbacks Article to Speech results are signed with HMAC-SHA256 so the receiving server can verify that they came from Moknah. See [Article to Speech](../api/article-to-speech.md#verifying-the-signature). Callback URLs that point to private network addresses are refused. ### Your content - Content is private to the account that created it, and to its team where the team's permissions allow. - Videos uploaded for burning subtitles, and the subtitled copies, are deleted right after use or after 10 minutes at most. - Cloned voices that go unused are deleted automatically; see [Voice Cloning](../products/voice-cloning.md). - An account can be deleted by its owner at https://moknah.io/account/delete/. The full terms are in the privacy policy at https://moknah.io/privacy/ and the terms of service at https://moknah.io/terms/. ### Content moderation Text sent for speech generation is checked automatically, in the web app, the API, the streams and MCP alike. Text that clearly breaks the content policy is refused (`CONTENT_REJECTED`). Text that may break it can be flagged for review by the Moknah team while the audio is still returned. The policy is at https://moknah.io/content-policy/. ### Voice rights Clone only a voice you own or have permission to use. ### What this documentation does not contain No secret, customer record or private configuration is published here. An AI system cannot obtain another user's data, keys or content through these documents or through the MCP server. ### Reporting a problem Report a suspected vulnerability or a leaked key to support@moknah.io. --- # FAQ Section: FAQ URL: https://moknah.io/docs/md/faq/index.md > Short answers to common questions about Moknah, including credits, text length, languages, voices, commercial use, the API and AI assistants. ### General #### What is Moknah? A multilingual AI audio platform, with in-depth Arabic support: text to speech, audiobook production, speech to text and subtitles, voice cloning, voice changing, dubbing, translation and PDF to Word, as a web app, an API and an MCP server. See [Platform overview](../platform/overview.md). #### Is Moknah only for Arabic? No. Voices speak more than 130 languages. Arabic gets extra care: diacritics, dialects and Arabic text processing. See [Languages](../platform/languages.md). #### Who is Mo, the little robot on every page? Mo is Moknah's mascot: a small voice robot who keeps you company, follows your jobs, and can be cared for like a pet. He is optional and never blocks a feature; you can hide him in Settings, on the Mo tab. See [Mo, the Moknah mascot](../platform/mo.md). #### Is there a free plan? Yes, with credits every month and no credit card. The current amount and what the plan includes are in [Pricing](../pricing/index.md). #### Can I use the audio commercially? Yes. Audio made with your account can be used commercially under your subscription terms. ### Credits and pricing #### How are credits counted? By the amount of work: characters for speech and translation, minutes for transcription, pages for OCR, seconds for dubbing. Text to speech also depends on the text processing mode, the voice and the mode or engine. The estimate is always shown before generating. See [Pricing](../pricing/index.md). #### Can I buy credits without a subscription? Yes, at any time and in any amount. #### What happens if generation fails after I was charged? The credits are refunded, automatically for speech to text and Article to Speech, and through an automatically created refund request for REST text to speech. See [Pricing](../pricing/index.md#refunds-for-failed-work). ### Text and audio #### Is there a text limit? Text to Speech and the REST endpoint take up to 1,500 characters per clip. For longer content, Audio Studio handles whole books, chapter by chapter. See [Limits](../limits/index.md). #### Which formats can I download? Audio as MP3 or WAV, subtitles as SRT or VTT, PDF conversions as Word. Audio Studio can also export a timeline for Premiere Pro and DaVinci Resolve. The API offers more audio formats; see [Generate speech](../api/tts-generate.md#output-formats). #### Why does the same text sound a little different each time? The voice performs the text fresh every time, like an actor. Lower Temperature for more consistent results. #### Why does the choice of voice matter so much? The result takes on the character of the voice: its tone, energy and dialect. Pick a voice that already sounds the way you want. #### A word is pronounced wrong. What can I do? For Standard Arabic choose Arabic Tashkeel. Add diacritics to the unclear word yourself, write numbers and abbreviations as words, or try another voice. #### How do I get an Arabic dialect? Choose a voice that speaks the dialect, keep Basic text processing, and use one of the emotion modes. ### Voices #### Can I use my own voice? Yes. Clone it from one to five recordings and it appears in your voice list. See [Voice Cloning](../products/voice-cloning.md). #### What happens to a cloned voice I stop using? It is deleted automatically after a period without use, after a warning by email. The current period is in [Limits](../limits/index.md#upload-limits). ### Developers #### How do I integrate Moknah into my product? Create an API key in the dashboard and follow [Integrate text to speech](../workflows/tts-integration.md). API access is a plan feature; see [Pricing](../pricing/index.md). #### Can I send requests in parallel? No. REST text to speech runs one request at a time per account, and each streaming service allows one open stream. Queue your requests. See [Limits](../limits/index.md). #### Is there an API for dubbing, voice cloning, voice changer, translation or PDF to Word? No. Those tools are used in the web app. The API covers text to speech, speech to text, the voice list and Article to Speech. #### What is the WordPress plugin? It adds a spoken version with word highlighting to the posts of a WordPress site, using the Article to Speech service. See [Article Studio](../products/article-studio.md). ### AI assistants #### Can I use Moknah from ChatGPT or Claude? Yes, through AI Connect. See [AI Connect](../products/ai-connect.md). #### Will an assistant spend my credits without asking? No. Billable tools return an estimate first and act only after you approve. ### Support Write to support@moknah.io.