Phonemize API: preview pronunciation before you render — Audra

Every batch pipeline eventually ships an audio file where the voice says the company name wrong, and the fix is downstream embarrassment. POST /v2/phonemize is the preflight check: it shows you the phoneme string synthesis will actually use, before you spend credits rendering a full script.

This post covers the endpoint, what its response tells you, inline IPA markup for overrides, and the workflow that pairs it with the per-account lexicon.

The endpoint

POST /v2/phonemize takes the same voice-aware text preview you would render: a text field (up to 10,000 characters), optional voice (default june), and optional render_mode. It does not consume credits and returns no audio — just the phoneme-level view of what synthesis would speak.

curl
curl https://audratalks.com/v2/phonemize \
  -H "Authorization: Bearer sk-audra-..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Kubernetes, kubectl, and Audra deploy to Modal.","voice":"arthur"}' 

Python
import requests

resp = requests.post(
    "https://audratalks.com/v2/phonemize",
    headers={"Authorization": "Bearer sk-audra-..."},
    json={"text": "Kubernetes, kubectl, and Audra deploy to Modal.", "voice": "arthur"},
    timeout=120,
)
resp.raise_for_status()
result = resp.json()

JavaScript
const res = await fetch("https://audratalks.com/v2/phonemize", {
  method: "POST",
  headers: { Authorization: "Bearer sk-audra-...", "Content-Type": "application/json" },
  body: JSON.stringify({ text: "Kubernetes, kubectl, and Audra deploy to Modal.", voice: "arthur" }),
});
if (!res.ok) throw new Error(await res.text());
const result = await res.json();

Reading the response

The response has three fields. input is your text after normalization and lexicon application — what synthesis actually speaks from; read it first to catch normalization surprises (URLs expanded, currency spoken). phonemes is the IPA phoneme string when is_phonemes is true. And that flag matters: phonemes is null on the plain-text path — G2P still runs inside synthesis, so null does not mean phonemization was skipped.

Inline IPA overrides

When a term is persistently wrong, force its pronunciation inline with IPA markup: Audra [ˈɔːdrə](/ˈɔːdrə/) renders the word with exactly that phoneme sequence on Essential voices. Test the markup through /v2/phonemize first — free — then bake it into the script or promote it to a lexicon entry.

The workflow: check, then lock

• Draft the script's hard parts (names, acronyms, jargon) through /v2/phonemize — costs nothing.
• Fix one-offs inline with IPA markup; re-check through phonemize until it reads right.
• Terms that recur across scripts belong in the per-account lexicon (up to 100 entries), which applies to every render automatically — the lexicon post has that API.
• Only then render the full script for real credits.

Failure modes

• 400 on invalid voice or text over 10,000 characters — phonemize has a tighter limit than speech; check long docs in sections.
• 502 when the TTS worker is cold — retry after a short backoff; this is transient infrastructure, not your text.
• Over-trusting input: normalization can expand an acronym you wanted spoken as-is; spot-check before rendering.

Persistent pronunciation overrides: the per-account lexicon post. Phoneme markup reference on Essential: /docs#pronunciation.