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

# CLI

> Supertone CLIでターミナルから音声を生成・ストリーミング・一括処理し、ボイスを管理しましょう — クイックスタート、コマンド、レシピ、トラブルシューティング。

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

コード不要で、ターミナルから直接テキストを音声に変換できます。Supertone CLIは文字列・ファイル・標準入力（stdin）から合成し、スピーカーへリアルタイムでストリーミングし、ディレクトリ全体を一括処理し、ボイス・使用量・クレジットを管理します。

ソース: [supertone-inc/supertone-cli](https://github.com/supertone-inc/supertone-cli)。

## クイックスタート

<Steps>
  <Step title="インストール">
    ```bash theme={"dark"}
    pip install "supertone-cli[stream]"
    ```

    Python 3.12+が必要です。`[stream]`の追加オプションでリアルタイム再生が有効になります。
  </Step>

  <Step title="API キーを設定">
    ```bash theme={"dark"}
    export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
    ```
  </Step>

  <Step title="聴いてみる">
    ```bash theme={"dark"}
    supertone tts "ターミナルから発する最初のひとこと。" \
      --voice 91992bbd4758bdcf9c9b01 -m sona_speech_1 --stream
    ```

    音声が聞こえれば準備完了です。✅
  </Step>
</Steps>

<Note>
  アプリケーションコードに組み込みますか？ [Python](/ja/docs/developer-tools/python)または[TypeScript](/ja/docs/developer-tools/typescript) SDKを使用してください。AIエージェント向けは[MCP](/ja/docs/developer-tools/mcp)を参照してください。
</Note>

## インストール

<Tabs>
  <Tab title="pip">
    ```bash theme={"dark"}
    pip install supertone-cli
    ```
  </Tab>

  <Tab title="ストリーミング対応">
    ```bash theme={"dark"}
    pip install "supertone-cli[stream]"
    ```
  </Tab>
</Tabs>

Python 3.12+が必要です。`[stream]`の追加オプションは`--stream`によるシステムスピーカーへのリアルタイム再生を有効にします。

## 認証

<Tabs>
  <Tab title="環境変数">
    ```bash theme={"dark"}
    export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
    ```
  </Tab>

  <Tab title="設定ファイル">
    ```bash theme={"dark"}
    supertone config init             # 対話形式のセットアップ
    supertone config set api_key Kp9mZ3xQ7v...
    ```

    `~/.config/supertone/config.toml`に保存されます。
  </Tab>
</Tabs>

<Accordion title="デフォルト値を設定して入力を減らす">
  デフォルト値を一度保存しておけば、毎回の呼び出しで該当するフラグを省略できます:

  | 設定キー            | 省略時の用途        | デフォルト           |
  | --------------- | ------------- | --------------- |
  | `api_key`       | 常時            | —               |
  | `default_voice` | `--voice`未指定時 | —               |
  | `default_model` | `--model`未指定時 | `sona_speech_2` |
  | `default_lang`  | `--lang`未指定時  | `ko`            |

  ```bash theme={"dark"}
  supertone config set default_voice 20160a4c5ba38967330c84
  supertone config set default_lang en
  ```
</Accordion>

## 音声合成

```bash theme={"dark"}
# 文字列から
supertone tts "ターミナルからこんにちは。" --voice VOICE_ID -o output.wav

# ファイルから
supertone tts -i input.txt -v VOICE_ID -o output.wav

# 標準入力（stdin）から — パイプに対応
echo "パイプで渡したテキスト。" | supertone tts -v VOICE_ID -o output.wav

# 保存せずリアルタイム再生（[stream] 追加オプションが必要）
supertone tts "これはリアルタイムで再生されます。" -v VOICE_ID -m sona_speech_1 --stream

# 形式・ボイス設定の調整
supertone tts "もっと遅く、もっと低く。" -v VOICE_ID --output-format mp3 --speed 0.9 --pitch -2

# フォルダ全体を一括処理 — 入力ごとにオーディオファイル1つ
supertone tts -i scripts/ --outdir audio/ -v VOICE_ID
```

## ボイス管理

```bash theme={"dark"}
supertone voices list                                  # Supertoneが提供するプリセットボイス
supertone voices list --type custom                    # 自分のクローンボイスのみ
supertone voices search --lang en --gender female      # プリセットの絞り込み
supertone voices get VOICE_ID                         # 詳細情報
supertone voices clone --name "My Voice" --sample sample.wav
supertone voices edit VOICE_ID --name "Renamed"
supertone voices delete VOICE_ID --yes               # --yesは確認をスキップ
```

## 長さの予測と使用量の追跡

`tts-predict`は、クレジットを**消費せずに**長さとクレジットコストを見積もります — 大量の一括処理の前に便利です。

```bash theme={"dark"}
supertone tts-predict "これはどのくらいの長さになりますか?" -v VOICE_ID

supertone usage balance
supertone usage analytics --start 2026-04-01 --end 2026-04-30
supertone usage voices    --start 2026-04-01 --end 2026-04-30
```

## レシピ

<AccordionGroup>
  <Accordion title="スクリプトのフォルダを一括ナレーション">
    `.txt`ファイルを1つのディレクトリにまとめ、一度に合成します:

    ```bash theme={"dark"}
    supertone tts -i chapters/ --outdir narration/ -v VOICE_ID --output-format mp3
    ```
  </Accordion>

  <Accordion title="LLMの出力をリアルタイムで読み上げ">
    任意のコマンドの出力をそのままリアルタイム音声へパイプします:

    ```bash theme={"dark"}
    my-llm "今日のヘッドラインを要約して" | supertone tts -v VOICE_ID -m sona_speech_1 --stream
    ```
  </Accordion>

  <Accordion title="jqでカスタムボイスを探す">
    `--format json`であらゆる読み取りコマンドをスクリプト化できます:

    ```bash theme={"dark"}
    supertone voices list --type custom --format json | jq '.[].name'
    ```
  </Accordion>

  <Accordion title="一括処理の前にコストを見積もる">
    入力を順に処理し、予測される長さを合計してクレジット消費前に把握します:

    ```bash theme={"dark"}
    for f in scripts/*.txt; do supertone tts-predict -i "$f" -v VOICE_ID; done
    ```
  </Accordion>
</AccordionGroup>

## リファレンス

<AccordionGroup>
  <Accordion title="対応モデル">
    `sona_speech_1`、`sona_speech_2`、`sona_speech_2_flash`、`sona_speech_2t`、`supertonic_api_1`、`supertonic_api_3`。各モデルの機能とトレードオフは[モデル](/ja/docs/core-concepts/models)を参照してください。
  </Accordion>

  <Accordion title="終了コード">
    | コード   | 意味         |
    | ----- | ---------- |
    | `0`   | 成功         |
    | `1`   | APIエラー     |
    | `2`   | 認証エラー      |
    | `3`   | 入力検証エラー    |
    | `130` | 中断（Ctrl-C） |
  </Accordion>
</AccordionGroup>

## トラブルシューティング

<AccordionGroup>
  <Accordion title="command not found: supertone">
    インストール先が`PATH`にないか、有効化されていない仮想環境にインストールされています。仮想環境を再度有効化するか、`pip install --user supertone-cli`で再インストールし、ユーザースクリプトのディレクトリを`PATH`に追加してください。
  </Accordion>

  <Accordion title="認証エラー（終了コード 2）">
    API キーが未設定か無効です。`echo $SUPERTONE_API_KEY`で確認するか、`supertone config set api_key your-api-key`を実行してください。キーは[Developer Console](https://console.supertoneapi.com)で取得できます。
  </Accordion>

  <Accordion title="--stream で音が出ない">
    リアルタイム再生にはストリーミングの追加オプション（`pip install "supertone-cli[stream]"`）と\*\*`sona_speech_1`モデル\*\*が必要です — `-m sona_speech_1`を渡してください。他のモデルは\*「Streaming requires sona\_speech\_1」\*エラーになります。その場合は`-o output.wav`でファイルに保存してください。
  </Accordion>

  <Accordion title="クレジット切れ（402）">
    残高がなくなると合成は停止します。`supertone usage balance`で確認し、[Developer Console](https://console.supertoneapi.com)でチャージしてください。
  </Accordion>
</AccordionGroup>

## 関連ドキュメント

<CardGroup cols={2}>
  <Card title="MCP" icon="robot" href="/ja/docs/developer-tools/mcp">
    Model Context Protocolを通じて、AIエージェントがSupertoneを呼び出せるようにします。
  </Card>

  <Card title="Python SDK" icon="python" href="/ja/docs/developer-tools/python">
    アプリケーションコード向けの同じAPI。
  </Card>
</CardGroup>