> ## 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. # 音声生成 > テキストから完成したオーディオファイルを生成します — Supertone TTS で最もよく使われる呼び出しです。リクエストフィールド、出力フォーマット、レスポンスの形式、結果の保存方法を解説します。 このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は[英語の原文](/en/docs/text-to-speech/create-speech)もあわせてご確認ください。 `create_speech` はテキストを完成したオーディオファイルに変換します。生成されたオーディオ全体がレスポンスボディに含まれて返されるため、そのまま保存または再生できます。 合成中のオーディオチャンクをストリーミングで受信したい場合（たとえば生成完了前に再生を開始したい場合）は、[Stream speech](/ja/docs/text-to-speech/stream-speech) をご利用ください。 ## 基本的な使い方 ```python theme={"dark"} 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()) ``` ```typescript theme={"dark"} 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).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)); } ``` ```bash theme={"dark"} 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` です。[モデル](/ja/docs/core-concepts/models) を参照してください。 | | `output_format` | — | `wav`（デフォルト）または `mp3` です。後述の [出力フォーマット](#output-formats) を参照してください。 | | `voice_settings` | — | ピッチ、抑揚、速度などです。[Voice settings](/ja/docs/text-to-speech/voice-settings) を参照してください。 | | `include_phonemes` | — | `true` の場合、音素シンボルとタイムスタンプを返します。[Pronunciation and phonemes](/ja/docs/text-to-speech/pronunciation-and-phonemes) を参照してください。 | | `normalized_text` | — | 発音正規化用のコンパニオンテキストです（現在は `sona_speech_2` 系の日本語向け）。[Normalized text](/ja/docs/text-to-speech/normalized-text) を参照してください。 | 完全なスキーマについては [Create speech (API リファレンス)](/ja/api-reference/endpoints/text-to-speech) をご覧ください。 ## 出力フォーマット | Format | `output_format` value | Content type | Use when | | ------------- | --------------------- | ------------ | -------------------------------------------------------------- | | WAV (default) | `wav` | `audio/wav` | ロスレスオーディオが必要な場合 — 本番のオーディオパイプライン、後段の加工処理、ゲーム／アニメーションアセットに最適です。 | | MP3 | `mp3` | `audio/mpeg` | エンドユーザー端末への配信向けにファイルサイズを抑えたく、ロスレス品質が不要な場合に適しています。 | `output_format` を省略すると、API はデフォルトで `wav` を使用します。同じオプションは [Stream speech](/ja/docs/text-to-speech/stream-speech) にも適用され、チャンクは指定されたフォーマットのバイナリで返されます。 ## レスポンス デフォルトでは、API はレスポンスボディに **バイナリオーディオ** を返します。レスポンスには以下の 2 つの便利なヘッダーが付与されます。 | Header | Meaning | | ---------------- | ------------------------------------------------------ | | `Content-Type` | `output_format` に対応する `audio/wav` または `audio/mpeg` です。 | | `X-Audio-Length` | 生成されたオーディオの長さ（秒、float）です。 | ### `include_phonemes=true` の場合 音素タイムスタンプを有効にすると、レスポンスは **JSON に切り替わり**、Base64 エンコードされたオーディオペイロードと音素配列が並んで返されます。 ```json theme={"dark"} { "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](/ja/docs/text-to-speech/pronunciation-and-phonemes) を参照してください。 ## 結果の保存 ```python theme={"dark"} response = client.text_to_speech.create_speech(...) with open("speech.wav", "wb") as f: f.write(response.result.read()) ``` ```typescript theme={"dark"} 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).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](/ja/api-reference/endpoints/get-voice) を呼び出してボイスのデフォルトを取得してください。 * **生成前に見積もりましょう。** [`predict_duration`](/ja/docs/production/cost-and-usage#predict-duration) はクレジットを消費せずに想定されるオーディオ長を返します — UI ヒントやコスト試算に有用です。 * **長いテキスト。** raw API は `text` を 300 文字までに制限しています。Python と TypeScript の SDK は自動で分割・生成・結合します — [Long text](/ja/docs/text-to-speech/long-text) を参照してください。 * **空または極端に短い入力** は不自然な結果を生むことがあります。少なくとも完結した短い文を入力するようにしてください。 ## 関連項目 高速モデルと高品質モデルから TTS モデルを選びます。 300 文字を超えるテキストからオーディオを生成します。 ピッチ、抑揚、速度を調整します。 リクエストとレスポンスの完全なスキーマ。