# API overview

> 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.
