Skip to main content

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.

이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
한자, 숫자, 단위, 기호가 포함된 입력에서는 표기 형태와 실제 발화 형태가 달라지는 경우가 많습니다. normalized_text 필드를 사용하면 원본과 함께 발음 중심의 버전을 제공할 수 있으며, 엔진은 두 값을 모두 활용해 더 정확한 음성을 생성합니다. 원본 text는 의미와 맥락을 보존합니다. normalized_text는 해당 문장이 어떻게 발음되어야 하는지를 기술합니다.
normalized_text는 현재 sona_speech_2와 sona_speech_2_flash에서 사용되며 주로 일본어를 위해 설계되었습니다.

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

입력에 다음 요소가 포함된 경우 normalized_text를 text와 함께 사용해 주십시오.
  • 발음이 암묵적으로 결정되는 숫자(연도, 가격, 전화번호)
  • 단위 및 기호(10%, 170cm, $50)
  • 혼합 문자(영어 약어가 섞인 일본어, 한국어에 포함된 라틴 문자)
  • 읽기가 모호한 한자
  • 특수 기호(〜, ※, →)
오디오북, 내레이션, 안내방송, 캐릭터 보이스 등 발음 정확도가 중요한 작업에서는 강력히 권장됩니다. 짧고 가벼운 대화체 문장에는 보통 필요하지 않습니다.

​
기본 사용법

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",
)

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

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

​
관련 문서

모델

어떤 모델이 normalized_text를 지원하는지 확인하세요.

Create speech

전체 TTS 요청 레퍼런스입니다.