Supertone APIを通じてテキストを音声に変換するには、特定のボイスIDと共にテキスト、言語、スタイルなどの情報をAPIに渡す必要があります。 この文書は、Text-to-Speech機能の全体的な呼び出し構造とパラメータ設定方法、レスポンス形式、音声調整オプションまでステップバイステップでご案内します。

​
1. 呼び出しエンドポイントと基本構造

POST /v1/text-to-speech/{voice_id}

​
必須ヘッダー

x-sup-api-key: [YOUR_API_KEY]
Content-Type: application/json

​
パスパラメータ

  • voice_id：使用するボイスの固有ID

​
クエリパラメータ

  • output_format（選択）：生成するオーディオ形式。wav（デフォルト）、mp3から選択可能

​
2. リクエスト本文

リクエストはJSON形式で送信され、以下のフィールドを含むことができます：
フィールド必須説明
text✅音声に変換するテキスト（最大300文字）
language✅テキストの言語。ボイスがサポートする言語の中から選択（ko、en、ja）
style❌適用する感情スタイル (neutral, happy など)。未入力の場合、デフォルトスタイルを使用します。最初の値がデフォルトスタイルになります。
model❌使用する音声モデル（sona_speech_1）。省略時は自動適用
voice_settings❌音声のピッチ、イントネーション、速度を調節する高度なオプション（下記参照）

​
3. 全体リクエスト例

POST /v1/text-to-speech/91992bbd4758bdcf9c9b01?output_format=mp3
x-sup-api-key: [YOUR_API_KEY]
Content-Type: application/json

{
  "text": "안녕하세요, 수퍼톤 API입니다.",
  "language": "ko",
  "style": "neutral",
  "model": "sona_speech_1",
  "voice_settings": {
    "pitch_shift": 0,
    "pitch_variance": 1,
    "speed": 1
  }
}

​
4. voice_settings選択

voice_settingsは、生成される音声の発話感を細かく調整したい場合に使用できる高度なオプションです。
パラメータ説明許可範囲デフォルト値
pitch_shift音程の高低を調整します。
0は元のボイスの音程で、±12段階まで可能です。1段階は半音です。		-12 ~ +120
pitch_variance発話中のイントネーション変化の程度を調節します。
小さいほど平坦なイントネーション、大きいほど豊かなイントネーションを生成します。		0.1 ~ 21
speed発話速度を調節します。
1より小さいと遅くなり、大きいと速くなります。		0.5 ~ 21

​
5. レスポンス

成功時はオーディオストリーム（audio/wavまたはaudio/mpeg）でレスポンスされます。
オーディオの長さはヘッダーを通じて確認できます。 
X-Audio-Length: 3.42
上記の例は3.42秒分の音声が生成されたことを意味します。

​
6. 入力テキストに関する注意事項

  • テキストは最大300文字まで入力できます。
  • 短すぎる文章は発話が不自然になる可能性があります。
  • 韓国語、英語、日本語のみサポートされており、これ以外の言語は予期しない結果が発生する可能性があります。
  • 絵文字、特殊記号などは音声で読まれないか無視されます。

​
7. モデル選択

現在サポートするモデルはsona_speech_1一つです。
このパラメータは選択事項で、未入力時はデフォルトモデルが自動で適用されます。

​
8. Predict Duration APIで発話長さを先に確認する

音声生成なしでも、入力テキストが何秒分の発話を誘導するかを予測できます。 
POST /v1/predict-duration/{voice_id}
  • リクエスト方式はTTSと同じ
  • レスポンス例：
{
  "duration": 2.87
}
このAPIはクレジットを差し引きません。 使用量予測やプレビューUI実装時に有用に活用できます。