Text Rewriting Rules

The text-to-speech API supports text rewriting rules that normalize and expand certain patterns in the input text before synthesis. These rules help the TTS model properly pronounce numbers, currency amounts, email addresses, URLs, and alphanumeric codes.

Configuration

Rewrite rules are controlled by the rewrite_rules field of json_config. Its value is a single string: either a language or locale code (e.g. "en"), or "none" to disable rewriting. json_config goes in the setup message for WebSocket sessions, or in the request body for the REST endpoint:

import gradium

client = gradium.client.GradiumClient(api_key="your-api-key")

async with client.tts_realtime(
    voice_id="Bla6SbVMczYnOhfK",
    output_format="pcm",
    json_config={"rewrite_rules": "en"},
) as tts:
    await tts.send_text("The invoice came to $1500.")
    await tts.send_eos()
    ...

import gradium

client = gradium.client.GradiumClient(api_key="your-api-key")

result = await client.tts(
    setup={
        "voice_id": "Bla6SbVMczYnOhfK",
        "output_format": "wav",
        "json_config": {"rewrite_rules": "en"},
    },
    text="The total is $1500, invoice sent to foo.bar@gmail.com.",
)

with open("output.wav", "wb") as f:
    f.write(result.raw_data)

// Authentication uses a short-lived token; see the Browser WebSockets guide.
const url = new URL("wss://api.gradium.ai/api/speech/tts");
url.searchParams.set("token", token);
const ws = new WebSocket(url);

ws.addEventListener("open", () => {
  ws.send(JSON.stringify({
    type: "setup",
    model_name: "default",
    voice_id: "Bla6SbVMczYnOhfK",
    output_format: "pcm",
    json_config: {rewrite_rules: "en"},
  }));
});

curl -L -X POST https://api.gradium.ai/api/post/speech/tts \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Write to foo.bar@gmail.com about the 1500 euros.",
    "voice_id": "Bla6SbVMczYnOhfK",
    "output_format": "wav",
    "only_audio": true,
    "json_config": {"rewrite_rules": "en"}
  }' > output.wav

Default behavior

For both the production and beta models, when the selected voice has a language associated with it, the API enables that language’s rules by default. So a session using an English voice behaves as if you had passed "rewrite_rules": "en". Setting rewrite_rules yourself overrides this default.

Disabling rewriting: `none`

Pass "rewrite_rules": "none" to turn all rewrite rules off. Because of the language default described above, this is the only way to get unrewritten text for a voice that has a language: omitting the field enables the voice language’s rules, while "none" disables them.

{
  "json_config": {
    "rewrite_rules": "none"
  }
}

With rules disabled, only minimal text normalization is applied before synthesis.

Supported Languages and Locales

Each value enables the full set of rewriting rules for that language or locale:

Value	Language
`en`	English
`fr`	French
`fr-be`	French (Belgium)
`fr-ch`	French (Switzerland)
`de`	German
`es`	Spanish
`pt`	Portuguese
`none`	Rewriting disabled

Belgian and Swiss French share most of their rewriting with metropolitan French; the differences are in how dates, numbers and currency amounts are spoken, so pick fr-be or fr-ch when your audience is in those markets.

What Gets Rewritten

With a language or locale selected, the following are expanded into the spoken form of that language:

Numbers, including negative values and large magnitudes
Currency amounts, with the symbol before or after the amount
Email addresses
URLs
Alphanumeric codes and identifiers, such as reference or product codes
Dashed digit sequences, such as phone and account numbers

Years and small numbers are kept as written, and punctuation around a rewritten pattern is preserved.

Custom Rewrites: Pronunciation Dictionaries

Rewrite rules handle general patterns (numbers, currency amounts, emails, URLs). To rewrite specific words or phrases of your own (brand names, acronyms, domain jargon), use a pronunciation dictionary instead. The dictionary is not part of rewrite_rules or json_config: create it in the Gradium Studio (or via the pronunciations API) and pass its ID as pronunciation_id at the top level of the setup message, next to voice_id:

result = await client.tts(
    setup={
        "voice_id": "Bla6SbVMczYnOhfK",
        "output_format": "wav",
        "pronunciation_id": "bb1ckYhNHCcIJjdK",   # top level, not in json_config
        "json_config": {"rewrite_rules": "en"},   # pattern rules still apply
    },
    text="The text you want to generate.",
)

Dictionary entries are applied to the text first, then the pattern rules run on the result. The two combine freely. For example, a dictionary that expands your product’s acronym, plus "en" rules to read out prices and product codes. Pronunciation dictionaries apply to WebSocket sessions only; REST requests cannot use them, and only the pattern-based rewrite_rules are available there.

Best Practices

Match the value to the voice - use the language or locale of the voice you synthesise with, and rely on the default when they already match
Use the locale codes - fr-be and fr-ch read dates, numbers and amounts the way those markets expect
Disable deliberately - pass "none" when your text is already written the way it should be spoken

Getting Started

Text-to-Speech

Speech-to-Text

Speech-to-Speech

Shared

Real-time Recipes

Migrations

Voices

Self-Hosted

Resources

Configuration

Default behavior

Disabling rewriting: `none`

Supported Languages and Locales

What Gets Rewritten

Custom Rewrites: Pronunciation Dictionaries

Best Practices

​Configuration

​Default behavior

​Disabling rewriting: none

​Supported Languages and Locales

​What Gets Rewritten

​Custom Rewrites: Pronunciation Dictionaries

​Best Practices

Configuration

Default behavior

Disabling rewriting: `none`

Supported Languages and Locales

What Gets Rewritten

Custom Rewrites: Pronunciation Dictionaries

Best Practices