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

# 発音と音素

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

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

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

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

<Note>
  `sona_speech_2`、`sona_speech_2_flash`、`sona_speech_1` で対応しています。`supertonic_api_3` および `supertonic_api_1` では対応していません。
</Note>

## 使い方

<Tabs>
  <Tab title="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")
    ```
  </Tab>

  <Tab title="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`);
    }
    ```
  </Tab>

  <Tab title="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]
      }
    }
    ```
  </Tab>
</Tabs>

## レスポンスの形

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

## 関連項目

<CardGroup cols={2}>
  <Card title="リップシンクの例" icon="face-smile" href="/ja/docs/examples/lip-sync-phonemes">
    音素 → ビセムのパイプラインを構築します。
  </Card>

  <Card title="Normalized text" icon="language" href="/ja/docs/text-to-speech/normalized-text">
    曖昧な入力の発音を改善します。
  </Card>
</CardGroup>