# AI agent guide

> 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/<slug>.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/<slug>` |

## 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 <API key>`. 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://<name>` resources.
