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.
このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は英語の原文もあわせてご確認ください。 create_speech はテキストを完成したオーディオファイルに変換します。生成されたオーディオ全体がレスポンスボディに含まれて返されるため、そのまま保存または再生できます。
合成中のオーディオチャンクをストリーミングで受信したい場合（たとえば生成完了前に再生を開始したい場合）は、Stream speech をご利用ください。
基本的な使い方
import os
from supertone import Supertone
VOICE_ID = "20160a4c5ba38967330c84" # replace with your voice ID
with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
response = client.text_to_speech.create_speech(
voice_id=VOICE_ID,
text="Hello from Supertone.",
language="en",
model="sona_speech_1",
output_format="wav",
)
with open("speech.wav", "wb") as f:
f.write(response.result.read())
import { Supertone } from "@supertone/supertone";
import * as fs from "node:fs";
const VOICE_ID = "20160a4c5ba38967330c84"; // replace with your voice ID
const client = new Supertone({ apiKey: process.env.SUPERTONE_API_KEY });
const response = await client.textToSpeech.createSpeech({
voiceId: VOICE_ID,
apiConvertTextToSpeechUsingCharacterRequest: {
text: "Hello from Supertone.",
language: "en",
model: "sona_speech_1",
outputFormat: "wav",
},
});
if (response.result instanceof Uint8Array) {
fs.writeFileSync("speech.wav", response.result);
} else if (response.result && "getReader" in response.result) {
const reader = (response.result as ReadableStream<Uint8Array>).getReader();
const chunks: Uint8Array[] = [];
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (value) chunks.push(value);
}
fs.writeFileSync("speech.wav", Buffer.concat(chunks));
}
VOICE_ID="20160a4c5ba38967330c84" # replace with your voice ID
curl -X POST "https://supertoneapi.com/v1/text-to-speech/$VOICE_ID" \
-H "x-sup-api-key: $SUPERTONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello from Supertone.",
"language": "en",
"model": "sona_speech_1",
"output_format": "wav"
}' \
--output speech.wav
リクエストフィールド
| Field | Required | Description |
|---|
voice_id | ✅ | パスパラメータ — キャラクターを指定します。 |
text | ✅ | 合成するテキストです。1 回の API 呼び出しにつき最大 300 文字（SDK はそれより長いテキストを自動的にチャンク分割します）。 |
language | ✅ | 言語コードです。ボイスとモデルの両方が対応している必要があります。 |
style | — | 感情スタイルです（例: neutral, happy）。デフォルトはボイスの styles 配列の先頭が適用されます。 |
model | — | TTS モデルです。デフォルトは sona_speech_1 です。モデル を参照してください。 |
output_format | — | wav（デフォルト）または mp3 です。後述の 出力フォーマット を参照してください。 |
voice_settings | — | ピッチ、抑揚、速度などです。Voice settings を参照してください。 |
include_phonemes | — | true の場合、音素シンボルとタイムスタンプを返します。Pronunciation and phonemes を参照してください。 |
normalized_text | — | 発音正規化用のコンパニオンテキストです（現在は sona_speech_2 系の日本語向け）。Normalized text を参照してください。 |
出力フォーマット
| Format | output_format value | Content type | Use when |
|---|
| WAV (default) | wav | audio/wav | ロスレスオーディオが必要な場合 — 本番のオーディオパイプライン、後段の加工処理、ゲーム／アニメーションアセットに最適です。 |
| MP3 | mp3 | audio/mpeg | エンドユーザー端末への配信向けにファイルサイズを抑えたく、ロスレス品質が不要な場合に適しています。 |
output_format を省略すると、API はデフォルトで wav を使用します。同じオプションは Stream speech にも適用され、チャンクは指定されたフォーマットのバイナリで返されます。
レスポンス
デフォルトでは、API はレスポンスボディに バイナリオーディオ を返します。レスポンスには以下の 2 つの便利なヘッダーが付与されます。
| Header | Meaning |
|---|
Content-Type | output_format に対応する audio/wav または audio/mpeg です。 |
X-Audio-Length | 生成されたオーディオの長さ（秒、float）です。 |
include_phonemes=true の場合
音素タイムスタンプを有効にすると、レスポンスは JSON に切り替わり、Base64 エンコードされたオーディオペイロードと音素配列が並んで返されます。
{
"audio_base64": "UklGRnoGAABXQVZF...",
"phonemes": {
"symbols": ["", "h", "ɐ", "ɡ", "ʌ", ""],
"start_times_seconds": [0, 0.092, 0.197, 0.255, 0.29, 0.58],
"durations_seconds": [0.092, 0.104, 0.058, 0.034, 0.29, 0.162]
}
}
結果の保存
response = client.text_to_speech.create_speech(...)
with open("speech.wav", "wb") as f:
f.write(response.result.read())
import * as fs from "node:fs";
const response = await client.textToSpeech.createSpeech(...);
if (response.result instanceof Uint8Array) {
fs.writeFileSync("speech.wav", response.result);
} else if (response.result && "getReader" in response.result) {
const reader = (response.result as ReadableStream<Uint8Array>).getReader();
const chunks: Uint8Array[] = [];
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (value) chunks.push(value);
}
fs.writeFileSync("speech.wav", Buffer.concat(chunks));
}
ヒント
- スタイルは重要です。 ボイスごとにデフォルトスタイルが異なる場合があります。
style を明示的に指定するか、起動時に一度 Get voice を呼び出してボイスのデフォルトを取得してください。
- 生成前に見積もりましょう。
predict_duration はクレジットを消費せずに想定されるオーディオ長を返します — UI ヒントやコスト試算に有用です。
- 長いテキスト。 raw API は
text を 300 文字までに制限しています。Python と TypeScript の SDK は自動で分割・生成・結合します — Long text を参照してください。
- 空または極端に短い入力 は不自然な結果を生むことがあります。少なくとも完結した短い文を入力するようにしてください。
関連項目
モデルを選ぶ
高速モデルと高品質モデルから TTS モデルを選びます。
長いテキスト
300 文字を超えるテキストからオーディオを生成します。
Voice settings
ピッチ、抑揚、速度を調整します。
API リファレンス
リクエストとレスポンスの完全なスキーマ。
