> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mihu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pronunciation

> Tell the voices how to say your own words: brand names, products, abbreviations

A pronunciation dictionary says how your account's words are spoken, **per language** and, if you want, **per voice**.
"BMW" is "be me ve" in Turkish and "bee em double-you" in English; "iPhone" is "ayfon" in Turkish.

Every `POST /v1/audio/speech` request of your account uses its dictionary automatically: the rules for the request's
language (and the rules for every language), for its voice (and the rules for every voice). Nothing to add to the request.

You can also manage it in the console: **Pronunciation**, with a ▶ button to hear each word before and after saving.

## How a rule works

| Field | Meaning |
| - | - |
| `text` | The word or words as written, 1-100 characters (`BMW`, `BMW Group`, `C++`) |
| `alias` | How they are said, **written in that language's own spelling**, 1-200 characters (`be me ve`) |
| `language` | `tr`, `en`, `de`, `fr`, `es`, `it`, `ru`, or `*` for every language (default `*`) |
| `case_sensitive` | `false` (default): `BMW` also matches `bmw`; `true`: only as written |
| `voices` | Voice ids the rule is for; empty (default) = every voice. A rule for one voice wins over a rule for all |

* **Whole words only:** `BMW` does not change `BMWs` or `xBMW`.
* **Turkish endings stay:** `BMW'nin` is said `be me ve'nin`, `iPhone'unuz` → `ayfon'unuz`.
* **Longest first:** with rules for `BMW Group` and `BMW`, "BMW Group" uses the first. A replaced word is never
  matched again.
* **Then the normal reading:** after the dictionary, numbers, dates, amounts and addresses are read as always.
* The voices read text, not phonetic symbols: write the alias the way a speaker of the language would spell the sound.
  Listen to it once; if it is not right, change the spelling (spaces, hyphens, doubled letters) and listen again.

A dictionary belongs to your account in one region: rules made on `tts.eu.mihu.ai` are used there, rules made on
`tts.tr.mihu.ai` there. Up to 1,000 rules per account.

## Add a rule

```bash theme={null}
curl -s https://tts.eu.mihu.ai/v1/pronunciations -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"text": "BMW", "alias": "be me ve", "language": "tr"}'
```

```json theme={null}
{"id": "1c117cbd-130c-4408-99d2-e1a1ad077c4f", "object": "pronunciation", "text": "BMW", "alias": "be me ve",
 "language": "tr", "case_sensitive": false, "voices": [], "created_at": 1794834610, "updated_at": 1794834610}
```

A rule for the same words, language and voices replaces the earlier one. Several at once (`201`, `{"object": "list", "data": [...]}`):

```bash theme={null}
curl -s https://tts.eu.mihu.ai/v1/pronunciations -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"rules": [{"text": "BMW", "alias": "be me ve", "language": "tr"},
                 {"text": "BMW", "alias": "bee em double-you", "language": "en"}]}'
```

`"replace": true` next to `"rules"` makes the list your whole dictionary (an import: earlier rules are removed).

## List, change, delete

| | |
| - | - |
| `GET /v1/pronunciations` | Your rules; `?language=tr` gives Turkish and every-language rules |
| `GET /v1/pronunciations/{id}` | One rule |
| `PATCH /v1/pronunciations/{id}` | Change fields: `{"alias": "be-me-ve"}` |
| `DELETE /v1/pronunciations/{id}` | Remove it |

Invalid fields answer `400` with the field in `error.param`; a rule of another account answers `404`.

## Speech requests

Nothing changes in your requests. Each answer says how many rules were used in the `X-Pronunciations` header. To read
a text without your dictionary (for example to compare), send `"pronunciations": false`:

```json theme={null}
{"model": "mihu-ses-v1", "input": "iPhone'unuz yarın teslim edilecek.", "language": "tr", "voice": "alp",
 "pronunciations": false}
```

## Speech-to-text: the same words as hints

So that speech-to-text writes your words back the way they are written ("be me ve" → "BMW"), give the dictionary's
words to Umay as [`hints`](https://developers.mihu.ai/stt/native-api) (Turkish):

```bash theme={null}
WORDS=$(curl -s "https://tts.eu.mihu.ai/v1/pronunciations?language=tr" -H "Authorization: Bearer $KEY" \
  | jq -r '[.data[].text] | unique | join(",")')
curl https://stt.eu.mihu.ai/v1/audio/transcriptions -H "Authorization: Bearer $KEY" \
  -F file=@call.wav -F model=umay -F language=tr -F hints="$WORDS"
```

The console's **Speech to Text** page does this for you: the dictionary's words appear as hints (dashed) when you
transcribe Turkish.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.