> ## 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.

# 発音と音素

> リップシンク、アニメーション、発音制御のための音素シンボルとタイムスタンプを取得します。

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

Supertone API は、オーディオに加えて **音素データ** を返すことができます — モデルが発話した個々の音単位と、それぞれの開始時刻および継続時間です。これは、ゲームやアニメーションのリップシンクの駆動、カラオケ風の単語ハイライト表示、発音解析に必要なデータです。

有効化するには、TTS リクエストで `include_phonemes: true` を指定してください。

> [!NOTE]
>
> `sona_speech_2`、`sona_speech_2_flash`、`sona_speech_1` で対応しています。`supertonic_api_3` および `supertonic_api_1` では対応していません。

## 使い方

**Python**

```python theme={"dark"}
import base64
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, world.",
        language="en",
        include_phonemes=True,
    )

    result = response.result
    with open("speech.wav", "wb") as f:
        f.write(base64.b64decode(result.audio_base64))

    for symbol, start, duration in zip(
        result.phonemes.symbols,
        result.phonemes.start_times_seconds,
        result.phonemes.durations_seconds,
    ):
        print(f"{symbol!r} at {start:.3f}s for {duration:.3f}s")
```

**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, world.",
    language: "en",
    includePhonemes: true,
  },
});

const result = response.result as {
  audioBase64: string;
  phonemes?: {
    symbols?: string[];
    startTimesSeconds?: number[];
    durationsSeconds?: number[];
  };
};

fs.writeFileSync("speech.wav", Buffer.from(result.audioBase64, "base64"));

const symbols = result.phonemes?.symbols ?? [];
const starts = result.phonemes?.startTimesSeconds ?? [];
const durations = result.phonemes?.durationsSeconds ?? [];

for (let i = 0; i < symbols.length; i++) {
  console.log(`${symbols[i]} at ${starts[i].toFixed(3)}s for ${durations[i].toFixed(3)}s`);
}
```

**cURL**

```bash theme={"dark"}
VOICE_ID="20160a4c5ba38967330c84"

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, world.",
    "language": "en",
    "include_phonemes": true
  }'
```

JSON を返します（バイナリオーディオではありません）:

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

## レスポンスの形

| Field | Description |
| - | - |
| `audio_base64` | リクエストで指定した `output_format`（`wav` または `mp3`）の Base64 エンコード済みオーディオです。 |
| `phonemes.symbols` | IPA 形式の音素シンボルです。空文字列は無音／ポーズを表します。 |
| `phonemes.start_times_seconds` | 各シンボルのクリップ内開始時刻です。 |
| `phonemes.durations_seconds` | 各シンボルの継続時間です。 |

3 つの音素配列はインデックスで対応しています — `symbols[i]`、`start_times_seconds[i]`、`durations_seconds[i]` は同じ 1 つの音素を指します。

## 音素データ付きのストリーミング

`include_phonemes: true` で `stream_speech` を呼び出すと、レスポンスは **NDJSON**（改行区切り JSON）になります。各行は、固有の `audio_base64` と対応する `phonemes` データを含む 1 つのチャンクです。

```jsonl theme={"dark"}
{"audio_base64":"...","phonemes":{"symbols":["","h"],"start_times_seconds":[0,0.05],"durations_seconds":[0.05,0.08]}}
{"audio_base64":"...","phonemes":{"symbols":["ɐ","ɡ"],"start_times_seconds":[0.13,0.19],"durations_seconds":[0.06,0.04]}}
```

到着した各行をパースして、リップシンクレンダラーをリアルタイムに駆動できます。

## 用途

* **ゲームやアニメーションのリップシンク。** 各音素をビセム（口の形）にマッピングし、オーディオと同期してビセムを再生します。多くのエンジンにはデフォルトの音素 → ビセム対応表が付属しています — Supertone のシンボルは標準的な IPA 形式で、ほとんどのリグと互換があります。
* **カラオケ／単語ハイライト。** 音素の開始時刻を使って、発話に合わせて単語をハイライト表示します。
* **発音解析。** 実際の音素を期待される音素列と比較し、語学学習アプリで発音をチェックします。

エンドツーエンドの例は [リップシンク用の音素生成](/ja/docs/examples/lip-sync-phonemes) を参照してください。

## 関連項目

> **[リップシンクの例](/ja/docs/examples/lip-sync-phonemes)**
>
> 音素 → ビセムのパイプラインを構築します。

> **[Normalized text](/ja/docs/text-to-speech/normalized-text)**
>
> 曖昧な入力の発音を改善します。


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