音声生成

このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は英語の原文もあわせてご確認ください。

create_speech はテキストを完成したオーディオファイルに変換します。生成されたオーディオ全体がレスポンスボディに含まれて返されるため、そのまま保存または再生できます。合成中のオーディオチャンクをストリーミングで受信したい場合（たとえば生成完了前に再生を開始したい場合）は、Stream speech をご利用ください。

基本的な使い方

Python
TypeScript
cURL

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 を参照してください。

完全なスキーマについては Create speech (API リファレンス) をご覧ください。

出力フォーマット

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]
  }
}

完全な構造については Pronunciation and phonemes を参照してください。

結果の保存

Python
TypeScript

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 リファレンス

リクエストとレスポンスの完全なスキーマ。

Announcement

基本的な使い方

リクエストフィールド

出力フォーマット

レスポンス

`include_phonemes=true` の場合

結果の保存

ヒント

関連項目

モデルを選ぶ

長いテキスト

Voice settings

API リファレンス

​基本的な使い方

​リクエストフィールド

​出力フォーマット

​レスポンス

​include_phonemes=true の場合

​結果の保存

​ヒント

​関連項目

モデルを選ぶ

長いテキスト

Voice settings

API リファレンス

基本的な使い方

リクエストフィールド

出力フォーマット

レスポンス

`include_phonemes=true` の場合

結果の保存

ヒント

関連項目