> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 노말라이즈드 텍스트

> 입력 텍스트와 함께 발음 중심의 버전을 짝지어 전달함으로써, 특히 일본어의 발음 정확도를 향상시킵니다.

<Note>
  이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/text-to-speech/normalized-text)을 함께 확인해 주세요.
</Note>

한자, 숫자, 단위, 기호가 포함된 입력에서는 표기 형태와 실제 발화 형태가 달라지는 경우가 많습니다. `normalized_text` 필드를 사용하면 원본과 함께 **발음 중심의 버전**을 제공할 수 있으며, 엔진은 두 값을 모두 활용해 더 정확한 음성을 생성합니다.

원본 `text`는 의미와 맥락을 보존합니다. `normalized_text`는 해당 문장이 **어떻게 발음되어야 하는지**를 기술합니다.

<Note>
  `normalized_text`는 현재 `sona_speech_2`와 `sona_speech_2_flash`에서 사용되며 **주로 일본어를 위해 설계**되었습니다.
</Note>

## 노말라이즈드 텍스트가 유용한 경우

입력에 다음 요소가 포함된 경우 `normalized_text`를 `text`와 함께 사용해 주십시오.

* 발음이 암묵적으로 결정되는 **숫자**(연도, 가격, 전화번호)
* **단위 및 기호**(`10%`, `170cm`, `$50`)
* **혼합 문자**(영어 약어가 섞인 일본어, 한국어에 포함된 라틴 문자)
* **읽기가 모호한 한자**
* **특수 기호**(`〜`, `※`, `→`)

오디오북, 내레이션, 안내방송, 캐릭터 보이스 등 발음 정확도가 중요한 작업에서는 **강력히 권장**됩니다. 짧고 가벼운 대화체 문장에는 보통 필요하지 않습니다.

## 기본 사용법

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    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",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    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",
      },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"dark"}
    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
    ```
  </Tab>
</Tabs>

## LLM으로 일본어 노말라이즈드 텍스트 생성하기

가장 일반적인 패턴은 LLM을 한 번 호출하여 노말라이즈드 버전을 생성한 뒤, `text`와 `normalized_text`를 함께 TTS API로 전달하는 것입니다. 아래 프롬프트는 요청에 그대로 매핑할 수 있는 깔끔한 JSON 출력을 생성합니다.

```text theme={"dark"}
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": "きょうはじゅっパーセントオフだよ。しんちょうはひゃくななじゅっセンチメートル、たいじゅうはろくじゅっキログラムだって！"
}
```

## 팁

* **`text`는 자연스럽게 유지하세요.** `text` 안에 후리가나 같은 주석을 넣지 마십시오. 모든 발음 힌트는 `normalized_text`에 넣어야 합니다.
* **단어 대 단어로 맞추세요.** `normalized_text`는 `text`의 의미와 정확히 일치해야 합니다. 의역하거나 다시 쓰지 말고, 표기만 바꿔 주십시오.
* **LLM 출력을 캐시하세요.** 결정적인 입력(UI 문자열, 반복되는 안내방송)에 대해서는 `normalized_text`를 한 번만 생성하고 원본과 함께 저장해 주십시오.
* **필요 없으면 생략하세요.** 숫자, 단위, 모호한 한자가 없는 일상 대화체 문장에는 보통 `normalized_text`가 큰 도움이 되지 않습니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="모델" icon="layer-group" href="/ko/docs/core-concepts/models">
    어떤 모델이 `normalized_text`를 지원하는지 확인하세요.
  </Card>

  <Card title="Create speech" icon="comment" href="/ko/docs/text-to-speech/create-speech">
    전체 TTS 요청 레퍼런스입니다.
  </Card>
</CardGroup>