# Kurdish TTS

> Kurdish TTS is a text-to-speech (TTS), speech-to-text (STT), and voice-chat platform built specifically for the Kurdish language — Sorani (Central Kurdish, Arabic script), Kurmanji (Northern Kurdish, Latin script) and, for text-to-speech, Badini/Behdinî (Northern Kurdish written in the Arabic script). It is one of the only providers of Kurdish speech AI, offering 891 natural AI voices through its V5 engine, a free tier, mobile apps, and a paid developer HTTP API for TTS and STT.

## Products

- [Kurdish Text-to-Speech](https://www.kurdishtts.com/tts): Convert Kurdish (Sorani/Kurmanji/Badini) text to natural speech with 891 AI voices rendered by V5, including six voices dedicated to Badini. Built-in translation from 124+ languages into Sorani or Kurmanji, then speak. Download MP3/WAV.
- [Kurdish Speech-to-Text](https://www.kurdishtts.com/stt): Transcribe Kurdish audio (Sorani/Kurmanji) via file upload or live streaming. Supports speaker diarization and word-level timestamps.
- [Kurdish Voice Chat](https://www.kurdishtts.com/conversation): Natural voice conversations with a Kurdish AI assistant in Sorani or Kurmanji, with one-tap translation of every message.
- [Kurdish Flow](https://www.kurdishtts.com/flow): Push-to-talk Kurdish dictation app for Mac and Windows — hold a hotkey, speak Sorani or Kurmanji, and the text is typed at your cursor in any app. Free for 500 words a week; Flow Pro is $15/month or $10/month billed yearly.
- [Kurdish Voice Cloning](https://www.kurdishtts.com/voice-clone): Upload or record a 3–30 second sample (6–10 seconds of clear speech is ideal) to create a custom Sorani or Kurmanji voice (Badini cannot be cloned). Free accounts get one preview-only clone; Creator (3 clones), Developer (10), Pro (20) and Business (30) can use clones in TTS and through the API.
- [Mobile app](https://www.kurdishtts.com/app): Kurdish TTS for iOS and Android with the same 891 voices, built for blind and low-vision users.

## Developer API

- [API reference](https://www.kurdishtts.com/docs/api): Full developer reference for the paid TTS + STT HTTP API — endpoints, authentication, parameters, and curl/Python/JavaScript examples.
- [Guides](https://www.kurdishtts.com/docs/guides): Step-by-step tutorials — [add Kurdish voice to Claude (MCP)](https://www.kurdishtts.com/docs/guides/claude-kurdish-voice), [Kurdish text-to-speech in Python/JS](https://www.kurdishtts.com/docs/guides/kurdish-text-to-speech-api), [transcribe Kurdish audio](https://www.kurdishtts.com/docs/guides/transcribe-kurdish-audio), [dictate Kurdish on Mac & Windows with Kurdish Flow](https://www.kurdishtts.com/docs/guides/kurdish-dictation).
- [OpenAPI 3.1 spec](https://www.kurdishtts.com/openapi.json): Machine-readable contract for the TTS + STT API.
- [API pricing](https://www.kurdishtts.com/pricing): Unified web/API plans (free, Creator, Developer, Pro, and Business), yearly billing, and credit packs.
- Authentication: `x-api-key` header. TTS and STT use separate API keys.
- API base URL: `https://www.kurdishtts.com/api`
  - `POST /api/tts-proxy` — buffered text-to-speech. Every request renders on V5; `model_version` = `v3`|`v4`|`v5` selects the compatible voice catalog and plan entitlement. Supports `speed`, audio formats, generation controls, and word timestamps.
  - `POST /api/tts-stream` — V5 text-to-speech streaming as SSE or raw 24 kHz PCM. The legacy `wav` option is accepted as a buffered compatibility response.
  - `POST /api/stt-proxy` — speech-to-text from an uploaded audio file (multipart: `file`, `dialect` = `sorani`|`kurmanji`).
  - `POST /api/stt-stream-connect` — open a live streaming STT session (returns a WebSocket URL).
  - `GET /api/get-speakers` — public, no-auth catalog of available voices (optional `?model_version=v3|v4|v5`; v5 lists the 20 curated speakers, the six `badini_` ones, and the 13 Cast and Studio ones; rendering the Cast and Studio ones needs a plan bought for the API). There is ONE model, V5 — model_version selects a speaker group, not an engine, and the groups share no ids.

## MCP Server (for AI agents)

- MCP endpoint: `https://www.kurdishtts.com/api/mcp` (Streamable HTTP transport).
- Setup guide: https://www.kurdishtts.com/docs/guides/claude-kurdish-voice
- Authentication: `Authorization: Bearer <ttsKey>` — or `<ttsKey>:<sttKey>` to use both key spaces in one session. Keys are 40 lowercase hex characters. TTS and STT keys are issued separately and are NOT interchangeable. Usage bills against your plan exactly like the HTTP API.
- No key required for: `initialize`, `tools/list`, and the `list_dialects`, `list_voices` and `get_plan` tools. Billed tools: `synthesize_speech`, `transcribe_audio`, `start_streaming_transcription`.
- Tools: `list_dialects`, `list_voices`, `get_plan`, `synthesize_speech`, `transcribe_audio`, `start_streaming_transcription`.
- Call `get_plan` first when a tool returns 401 or 403 — it reports your plan, remaining characters, which `model_version`s you may use and which speaker ids you may render.
- Plan ladder as JSON (no auth): `GET https://www.kurdishtts.com/api/plans`.
- Resource metadata (RFC 9728): `https://www.kurdishtts.com/.well-known/oauth-protected-resource`.
- Payload limits over MCP: 4,000 characters per synthesis in the default `mp3` container (600 with `format: "wav"`; free plans 500 either way), 3MB of decoded audio per transcription — use the HTTP API above for larger jobs.
- `synthesize_speech` takes `format` = `mp3` (default) | `opus` | `wav`. Tool-result audio is base64 in the model's context, so the container matters: for identical speech, mp3 is ~7.5x smaller than wav and opus ~11.5x.
- MCP cannot stream audio — a tool result is a single message. For a live voice agent, call `POST /api/tts-stream` directly with `stream_format: "sse"` (first audio in ~1s). `start_streaming_transcription` is for LISTENING (live mic → text), not for speaking.

### Getting a first call right

`list_voices` and `synthesize_speech` both default to `model_version` `v3`. A speaker id belongs to ONE catalog — always pass the same `model_version` to both, and never invent an id.

- Free plan, v3: `sorani_85`, `sorani_214`, `kurmanji_6`, `kurmanji_12`
- Free plan, v4: `sorani_1`, `sorani_986`, `kurmanji_236`, `kurmanji_233`
- Free plan, v5: `badini_story_m`, `badini_narrator_f` — the only V5 ids a free key may render.
- The rest of `v5`, including the Cast/Studio voices, requires a paid API plan. The other four `badini_` voices (`badini_narrator_m`, `badini_news_f`, `badini_teacher_f`, `badini_teacher_m`) are on every paid plan.
- A `badini_` id resolves on v5 whatever `model_version` you send, because it exists in no other catalog. Badini is TEXT-TO-SPEECH ONLY — `transcribe_audio` rejects it.

### Transcribing when you don't know the dialect

`dialect` selects the decoder and nothing detects it for you. Sorani audio transcribed as Kurmanji returns fluent, confident, WRONG text — HTTP 200, no warning, fully billed. Pass `dialect: "auto"` to `transcribe_audio` and it runs both decoders and returns both transcripts so the model can pick the coherent one; it bills the audio twice. Free plans truncate the returned transcript at 500 characters — the full audio is still transcribed and billed, only the text you get back is cut.

Other gotchas: `speed` is caller-facing (higher = faster); omit `temperature` entirely (`0.0` returns 422); on v4 a 200 response carrying `collapsed: true` is a FAILED generation; the Cast/Studio voices read Sorani and Kurmanji but are tagged `sorani`, so pass `dialect` to `synthesize_speech` for a correct Kurmanji read — they cannot read Badini, and pairing one with `dialect: "badini"` is refused with a 400 rather than returning wrong-dialect audio; the `moods` on a voice are not callable yet (`emotion` returns 400); `start_streaming_transcription` consumes one streaming session the instant it is called.

## Pricing

- [Plans](https://www.kurdishtts.com/plans): Website plans and free tier.
- [API pricing](https://www.kurdishtts.com/pricing): Developer API plans.

## Languages

- [Sorani — Central Kurdish (کوردی سۆرانی)](https://www.kurdishtts.com/ckb)
- [Kurmanji — Northern Kurdish (Kurdî Kurmancî)](https://www.kurdishtts.com/kmr)
- Badini / Behdinî — Northern Kurdish in the Perso-Arabic script (بادینی). Text-to-speech only, with six dedicated voices: [try it on /tts](https://www.kurdishtts.com/tts). No transcription, dictation, voice chat or translation.

## Optional

- [FAQ](https://www.kurdishtts.com/faq): Frequently asked questions about dialects, pricing, translation and accessibility.
- [About & founder](https://www.kurdishtts.com/about): The mission and founder (Bear Rizgar, from Qaladze, Southern Kurdistan).
- [Contact](https://www.kurdishtts.com/contact): Support and contact.