Pronunciation

A pronunciation entry tells the voice how to say a term. You write the term as it should sound, in the spelling of the language being spoken: Lokutor said as Lokútor, Stranger Things in Spanish as Estrénjer Zings. Entries apply before numbers and symbols are read, so 4K, C++ or COVID-19 can be overridden too. Entries live in pronunciation dictionaries on your account, and apply:

to every synthesis your account makes, from its default dictionary;
to an agent’s calls, from the dictionaries the agent uses (dashboard: the agent’s settings);
to one request, from the dictionaries it names and the entries it carries.

When several layers have the same term, the higher one wins: a request’s own entries, then the dictionaries it names, then the agent’s, then the default.

Writing a good respelling

Write it as it sounds in the language being spoken, with that language’s letters: Spanish Guatsáp for WhatsApp, Catalan or French spellings for those languages.
Mark the stressed syllable with an accent where the language uses one: Lokútor.
Lowercase. A short word in capitals (NASA) is read letter by letter, so it is rejected.
No digits: they are read as numbers. Write them as words.
Give a respelling per language you need. A term with no respelling for the language being spoken is said as written.

Entry

Field	Type	Required	Description
`term`	string	Yes	The text to replace, 1–64 characters. Matched as a whole word or phrase.
`say_as`	object	Yes	Respellings by language code, e.g. `{"es": "Lokútor", "fr": "Lokutôr"}`. 1–128 characters each.
`lang`	string	No	The term’s own language (e.g. `en` for an English brand name). Informational today.
`case_sensitive`	bool	No	`false` by default: `lokutor`, `Lokutor` and `LOKUTOR` all match.
`enabled`	bool	No	`true` by default.

Matching. Longest term first, left to right, one pass (a respelling is never matched again). A term matches only as a whole word: Teams matches in Teams. and Teams's, not in TeamsPro or Teams-like. In French, Catalan, Italian and Portuguese a term also matches after an elided article or preposition: l'iPhone, d'Amazon, dell'App, qu'Uber keep their l', d'… and respell only the term.

Dictionaries

Authenticate as for any API call (Authorization: Bearer or X-API-Key). An account has at most 50 dictionaries of at most 2,000 entries each, and at most one default.

`GET /v1/pronunciation-dictionaries`

{
  "dictionaries": [
    {
      "id": "6f1c…",
      "name": "Brand names",
      "is_default": true,
      "entries": [{"term": "Lokutor", "say_as": {"es": "Lokútor"}}],
      "created_at": "2026-10-26T19:00:00Z",
      "updated_at": "2026-10-26T19:00:00Z"
    }
  ]
}

`POST /v1/pronunciation-dictionaries`

Creates a dictionary. Body: name (1–100 characters), is_default (making one the default clears the previous one), entries. Returns 201 with the dictionary.

curl -X POST https://api.lokutor.com/v1/pronunciation-dictionaries \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Brand names", "is_default": true,
       "entries": [{"term": "WhatsApp", "say_as": {"es": "Guatsáp"}},
                   {"term": "Stranger Things", "say_as": {"es": "Estrénjer Zings"}, "lang": "en"}]}'

`GET`, `PUT`, `DELETE /v1/pronunciation-dictionaries/{id}`

PUT replaces the dictionary’s name, is_default and entries with the body’s. DELETE removes it; agents that used it simply stop using it.

Validation

Every save is checked by the same text processing the voice uses. A respelling the voice cannot say as written is refused with 400 and the problems found:

{
  "error": "some respellings cannot be said as written",
  "problems": [
    {"index": 0, "lang": "es", "level": "error", "message": "'NASA' is in capitals, so it would be spelled out letter by letter; write it in lowercase as it sounds"}
  ]
}

index is the entry’s position. level is error (not saved) or warning (saved: digits, which are read as numbers). A save with warnings and no errors succeeds (201 or 200) and returns the dictionary with its warnings under problems, in the same shape.

Per request

POST /tts/synthesize and WS /ws/tts take:

Parameter	Type	Description
`pronunciation_dictionary_ids`	string[]	Dictionaries to apply to this request, in priority order, on top of your default one. Unknown ids are ignored.
`pronunciations`	Entry[]	Entries for this request only; they win over every dictionary. A malformed entry is a `validation.invalid_request_format` error.
`temperature`	number	How varied the delivery is, `0.1`–`1.0`. Default `0.3`. Higher sounds livelier and less predictable. Outside the range is a `validation.invalid_request_format` error.

{
  "text": "Mira el nuevo episodio de Stranger Things en la app.",
  "voice": "F3",
  "language": "es",
  "pronunciations": [{"term": "Stranger Things", "say_as": {"es": "Estrénjer Zings"}}]
}

Markup

The text of any request may carry:

Markup	Effect
`<sub alias="ese ce">SC</sub>`	Says the alias instead of the enclosed text, once.
`<lang xml:lang="en">meeting</lang>`	Marks a span in another language: entries are looked up with that language’s respelling. The span is still read in the request’s language; speaking it in its own language mid-sentence is coming.

Anything else that looks like a tag is read as written.

Get Started

SDK

API Reference

Resources

Writing a good respelling

Entry

Dictionaries

`GET /v1/pronunciation-dictionaries`

`POST /v1/pronunciation-dictionaries`

`GET`, `PUT`, `DELETE /v1/pronunciation-dictionaries/{id}`

Validation

Per request

Markup

​Writing a good respelling

​Entry

​Dictionaries

​GET /v1/pronunciation-dictionaries

​POST /v1/pronunciation-dictionaries

​GET, PUT, DELETE /v1/pronunciation-dictionaries/{id}

​Validation

​Per request

​Markup

Writing a good respelling

Entry

Dictionaries

`GET /v1/pronunciation-dictionaries`

`POST /v1/pronunciation-dictionaries`

`GET`, `PUT`, `DELETE /v1/pronunciation-dictionaries/{id}`

Validation

Per request

Markup