> ## Documentation Index
> Fetch the complete documentation index at: https://supertone-b89202c8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 音声生成

> テキストから完成したオーディオファイルを生成します — Supertone TTS で最もよく使われる呼び出しです。リクエストフィールド、出力フォーマット、レスポンスの形式、結果の保存方法を解説します。

> [!NOTE]
>
> このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は[英語の原文](/en/docs/text-to-speech/create-speech)もあわせてご確認ください。

`create_speech` はテキストを完成したオーディオファイルに変換します。生成されたオーディオ全体がレスポンスボディに含まれて返されるため、そのまま保存または再生できます。

合成中のオーディオチャンクをストリーミングで受信したい場合（たとえば生成完了前に再生を開始したい場合）は、[Stream speech](/ja/docs/text-to-speech/stream-speech) をご利用ください。

## 基本的な使い方

**Python**

```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**

```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<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));
}
```

**cURL**

```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**

```python theme={"dark"}
response = client.text_to_speech.create_speech(...)
with open("speech.wav", "wb") as f:
    f.write(response.result.read())
```

**TypeScript**

```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<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](/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) を参照してください。
* **空または極端に短い入力** は不自然な結果を生むことがあります。少なくとも完結した短い文を入力するようにしてください。

## 関連項目

> **[モデルを選ぶ](/ja/docs/core-concepts/models)**
>
> 高速モデルと高品質モデルから TTS モデルを選びます。

> **[長いテキスト](/ja/docs/text-to-speech/long-text)**
>
> 300 文字を超えるテキストからオーディオを生成します。

> **[Voice settings](/ja/docs/text-to-speech/voice-settings)**
>
> ピッチ、抑揚、速度を調整します。

> **[API リファレンス](/ja/api-reference/endpoints/text-to-speech)**
>
> リクエストとレスポンスの完全なスキーマ。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.