Normalized text - Supertone API Documentation

For inputs that contain kanji, numbers, units, or symbols, the spoken form often diverges from the written form. The normalized_text field lets you provide a pronunciation-oriented version of your input alongside the original — the engine uses both to produce more accurate speech. The original text preserves meaning and context. The normalized_text describes how the sentence should be spoken.

normalized_text is currently used by sona_speech_2 and sona_speech_2_flash and is primarily designed for Japanese.

When normalized text helps

Pair normalized_text with text whenever your input contains:

Numbers with implicit pronunciation (years, prices, phone numbers)
Units and symbols (10%, 170cm, $50)
Mixed scripts (Japanese with English abbreviations, Latin words inside Korean)
Kanji with ambiguous readings
Special symbols (〜, ※, →)

It is strongly recommended for audiobooks, narration, announcements, and character voice work where pronunciation accuracy matters. For casual short conversational lines, it’s usually not necessary.

Basic usage

Python
TypeScript
cURL

VOICE_ID = "20160a4c5ba38967330c84"  # replace with your voice ID

response = client.text_to_speech.create_speech(
    voice_id=VOICE_ID,
    text="今日は10%オフだよ。身長は170cm、体重は60kg。",
    normalized_text="きょうはじゅっパーセントオフだよ。しんちょうはひゃくななじゅっセンチメートル、たいじゅうはろくじゅっキログラム。",
    language="ja",
    model="sona_speech_2",
)

const VOICE_ID = "20160a4c5ba38967330c84"; // replace with your voice ID

const response = await client.textToSpeech.createSpeech({
  voiceId: VOICE_ID,
  apiConvertTextToSpeechUsingCharacterRequest: {
    text: "今日は10%オフだよ。身長は170cm、体重は60kg。",
    normalizedText:
      "きょうはじゅっパーセントオフだよ。しんちょうはひゃくななじゅっセンチメートル、たいじゅうはろくじゅっキログラム。",
    language: "ja",
    model: "sona_speech_2",
  },
});

curl -X POST "https://supertoneapi.com/v1/text-to-speech/20160a4c5ba38967330c84" \
  -H "x-sup-api-key: $SUPERTONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "今日は10%オフだよ。身長は170cm、体重は60kg。",
    "normalized_text": "きょうはじゅっパーセントオフだよ。しんちょうはひゃくななじゅっセンチメートル、たいじゅうはろくじゅっキログラム。",
    "language": "ja",
    "model": "sona_speech_2"
  }' \
  --output speech.wav

Generating normalized Japanese text with an LLM

The most common pattern is to call an LLM once to produce the normalized version, then pass both text and normalized_text to the TTS API. The prompt below produces clean JSON output that you can map directly to the request.

You will receive a Japanese sentence that may contain kanji, numbers, symbols, and units.
For the given input, provide:
- the original text (natural Japanese using standard kanji–kana mixed notation, without furigana)
- the normalized text, converted according to the rules below.

Important:
- You must respond only with pure JSON format.
- Do not include any explanations or additional text.
- In original_text, do not include furigana (ruby annotations).

Response Format

{
  "original_text": "[natural Japanese Text]",
  "normalized_text": "[converted Text]"
}

Transcription Conversion Rules
1. Convert all kanji into hiragana using context-appropriate readings.
2. Keep katakana as is.
3. Preserve punctuation exactly as written.
4. Convert Arabic numerals into hiragana.
5. Expand units and English abbreviations into full katakana forms.
6. Apply natural phonological changes such as gemination and sound alternations.

Conversion Examples

{
  "original_text": "今日はどんな一日だったの？",
  "normalized_text": "きょうはどんないちにちだったの？"
}

{
  "original_text": "今日は10%オフだよ。身長は170cm、体重は60kgだって！",
  "normalized_text": "きょうはじゅっパーセントオフだよ。しんちょうはひゃくななじゅっセンチメートル、たいじゅうはろくじゅっキログラムだって！"
}

Tips

Keep text natural. Don’t include furigana or other annotations inside text. Put all pronunciation hints in normalized_text.
Match word-for-word. normalized_text should match the meaning of text exactly — don’t paraphrase or rewrite, only respell.
Cache LLM outputs. For deterministic inputs (UI strings, recurring announcements), generate normalized_text once and store it alongside the original.
Skip if not needed. Casual conversational lines without numbers, units, or ambiguous kanji usually don’t benefit from normalized_text.

Models

Which models accept normalized_text.

Create speech

Full TTS request reference.

​When normalized text helps

​Basic usage

​Generating normalized Japanese text with an LLM

​Tips

​Related

Models

Create speech

When normalized text helps

Basic usage

Generating normalized Japanese text with an LLM

Tips

Related