Pronunciation dictionaries

A pronunciation dictionary maps written forms to how they should be spoken. Each entry carries either an alias (replacement text, expanded at the gateway) or a phoneme (passed through to the model) — exactly one per entry. Attach a dictionary to any TTS request with pronunciation_dict_id.

Endpoints

Endpoint	Body	Returns
`GET /pronunciation-dicts`	—	`{"dicts": [{id, name, entry_count, created_at}]}`
`POST /pronunciation-dicts`	`{"name": "..."}` (required)	201, the dict
`GET /pronunciation-dicts/:id`	—	The dict with `entries`
`PATCH /pronunciation-dicts/:id`	`{"name": "..."}`	The dict
`DELETE /pronunciation-dicts/:id`	—	`{"id": "...", "deleted": true}` (soft delete)
`PUT /pronunciation-dicts/:id/entries`	`{"entries": [...]}`	`{"dict_id": "...", "entries": [...]}`

Unknown ids return 404 dict_not_found. PUT /entries replaces the full entry list — send every entry each time, not a delta.

Entries

A dictionary holds up to 1,000 entries.

Field	Constraint
`grapheme`	Required, 1–256 characters — the written form to match
`alias`	≤256 characters — replacement text, expanded before synthesis
`phoneme`	≤256 characters — phonetic spelling, passed to the model
`case_sensitive`	boolean — match `grapheme` exactly by case

Each entry carries exactly one of alias or phoneme. Create a dictionary and set its entries:

import requests

headers = {"Authorization": "Bearer sk_hopper_..."}
base = "https://api.withhopper.com"

dict_id = requests.post(f"{base}/pronunciation-dicts", headers=headers,
                        json={"name": "Support terms"}).json()["id"]

requests.put(f"{base}/pronunciation-dicts/{dict_id}/entries", headers=headers, json={
    "entries": [
        {"grapheme": "API", "alias": "A P I"},
        {"grapheme": "SQL", "alias": "sequel"},
        {"grapheme": "nginx", "phoneme": "ˈɛndʒɪnˌɛks"},
    ]
})

const base = "https://api.withhopper.com";
const headers = {
  Authorization: "Bearer sk_hopper_...",
  "Content-Type": "application/json",
};

const dict = await (await fetch(`${base}/pronunciation-dicts`, {
  method: "POST", headers, body: JSON.stringify({ name: "Support terms" }),
})).json();

await fetch(`${base}/pronunciation-dicts/${dict.id}/entries`, {
  method: "PUT",
  headers,
  body: JSON.stringify({
    entries: [
      { grapheme: "API", alias: "A P I" },
      { grapheme: "SQL", alias: "sequel" },
      { grapheme: "nginx", phoneme: "ˈɛndʒɪnˌɛks" },
    ],
  }),
});

curl -X PUT "https://api.withhopper.com/pronunciation-dicts/$DICT_ID/entries" \
  -H "Authorization: Bearer sk_hopper_..." \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {"grapheme": "API", "alias": "A P I"},
      {"grapheme": "SQL", "alias": "sequel"},
      {"grapheme": "nginx", "phoneme": "ˈɛndʒɪnˌɛks"}
    ]
  }'

How entries are applied

Pass the id on any TTS request:

{
  "model_id": "omnivoice",
  "transcript": "Connect to the API over SQL.",
  "voice": {"mode": "id", "id": "sarah"},
  "output_format": {"container": "wav", "sample_rate": 24000},
  "pronunciation_dict_id": "<dict_id>"
}

Alias entries are expanded at the gateway before the transcript reaches the model. Matching is whole-word and case-insensitive unless the entry sets case_sensitive.
Phoneme entries are not expanded; the gateway forwards them to the model as pronunciations: [{grapheme, phoneme, case_sensitive}].

Billing uses the submitted transcript, before alias expansion. Expansion itself is capped at 20,000 characters, 4× the 5,000-character transcript limit; a request that expands past it returns 400 transcript_too_long.

Get started

LLM

Text to Speech

Speech to Text

Platform

Pronunciation dictionaries

Endpoints

Entries

How entries are applied

​Endpoints

​Entries

​How entries are applied

Endpoints

Entries

How entries are applied