VoiceBox API Server

VOICEVOX音声合成を提供するFastAPI HTTPサーバー。
ずんだもん、春日部つむぎ、四国めたんなどのキャラクターボイスでテキストを読み上げます。

🚀 すぐに始めたい方は QUICKSTART.md をご覧ください

特徴

• FastAPI ベース: 高速で軽量なHTTPサーバー
• どこからでも呼び出し可能: curl、Python、任意のHTTPクライアントから利用可能
• 1つのサーバーで複数プロジェクト対応: 常駐型サーバーで効率的
• バックグラウンド実行: リクエストは即座にレスポンスを返す
• 複数の話者をサポート: キャラクターごとに速度設定可能
• macOS / Linux / Windows 対応

セットアップ

1. VOICEVOXアプリの起動

VOICEVOX公式サイトからアプリをダウンロード・インストールし、起動しておく。
デフォルトで http://localhost:50021 にAPIサーバーが立ち上がる。

2. 依存パッケージのインストール

python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

3. サーバー起動

./start_server.sh

または直接起動：

python api_server.py

サーバーが起動すると http://127.0.0.1:8767 でアクセス可能になります。

設定

環境変数（オプション）

.env ファイルを作成して以下を設定できます：

変数名	説明	デフォルト値
VOICEVOX_BASE_URL	VOICEVOXサーバーURL	http://localhost:50021
DEFAULT_SPEAKER	デフォルト話者名	zundamon

話者設定

yomiage-svr/config.py で話者（キャラクター）を設定できます。

利用可能な話者:

話者名	キャラクター	スタイル	速度
zundamon	ずんだもん	ノーマル	1.2
tsumugi	春日部つむぎ	ノーマル	1.2
metan	四国めたん	ノーマル	1.2

話者を追加・変更するには、yomiage-svr/config.py の SPEAKERS 辞書を編集してください。

API仕様

エンドポイント

POST /speech

テキストを音声合成して読み上げ

リクエストボディ:

{
  "text": "読み上げるテキスト",
  "speaker_name": "zundamon"  // 省略可
}

レスポンス:

{
  "status": "accepted",
  "message": "音声合成を開始しました: ...",
  "speaker_name": "zundamon"
}

GET /speakers

利用可能な話者一覧を取得

レスポンス:

{
  "zundamon": {
    "name": "zundamon",
    "display_name": "ずんだもん（ノーマル）",
    "style": "ノーマル",
    "speed_scale": 1.2
  },
  ...
}

GET /health

ヘルスチェック

レスポンス:

{
  "status": "ok"
}

使い方

curlコマンドで呼び出し

# デフォルト話者で読み上げ
curl -X POST http://127.0.0.1:8767/speech \
  -H "Content-Type: application/json" \
  -d '{"text": "こんにちは、音声合成のテストです"}'

# 話者を指定して読み上げ
curl -X POST http://127.0.0.1:8767/speech \
  -H "Content-Type: application/json" \
  -d '{"text": "春日部つむぎです", "speaker_name": "tsumugi"}'

# 利用可能な話者一覧を取得
curl http://127.0.0.1:8767/speakers

Pythonから呼び出し

client_example.py を参照：

import requests

# 音声合成リクエスト
response = requests.post(
    "http://127.0.0.1:8767/speech",
    json={"text": "こんにちは", "speaker_name": "zundamon"}
)
print(response.json())

詳細な使用例：

python client_example.py

他のプロジェクトから呼び出し

任意のプロジェクトから、HTTPリクエストでVoiceBox APIを呼び出せます：

# あなたのプロジェクトのコード
import requests

def speak(text: str, speaker: str = "zundamon"):
    requests.post(
        "http://127.0.0.1:8767/speech",
        json={"text": text, "speaker_name": speaker}
    )

# 使用例
speak("処理が完了しました")
speak("エラーが発生しました", speaker="metan")

直接実行

python server.py

プロジェクト構成

VoiceBox-API/
├── api_server.py               # FastAPIサーバー本体
├── server.py                   # MCPサーバー（旧版・オプション）
├── start_server.sh             # サーバー起動スクリプト
├── client_example.py           # クライアント使用例
├── yomiage-svr/
│   ├── __init__.py
│   ├── config.py               # 話者設定
│   ├── services/
│   │   ├── __init__.py
│   │   ├── voicevox_service.py # VOICEVOX HTTP API音声合成サービス
│   │   └── audio_service.py    # 音声再生サービス
│   └── tools/
│       ├── __init__.py
│       └── speech_tool.py      # Speechツール実装
├── requirements.txt            # 依存パッケージ
├── .env.example               # 環境変数サンプル
└── README.md                  # このファイル

MCPサーバー版（GitHub Copilot / Claude Desktop から呼び出し）

MCPとは？

MCP (Model Context Protocol) は、AIエージェント（GitHub Copilot、Claude Desktopなど）がツールを呼び出すための標準プロトコルです。MCPサーバーとして起動することで、AIエージェントから直接音声合成を実行できます。

セットアップ

1. MCP設定ファイルの配置

.vscode/mcp.json が既に配置されています：

{
  "mcpServers": {
    "yomiage": {
      "command": "${workspaceFolder}/venv/bin/python",
      "args": ["mcp_server.py"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}

2. Claude Desktop での設定（オプション）

Claude Desktopから利用する場合は、~/Library/Application Support/Claude/claude_desktop_config.json に追加：

{
  "mcpServers": {
    "voicevox-speech": {
      "command": "python",
      "args": ["/path/to/yomiage-svr/mcp_server.py"],
      "cwd": "/path/to/yomiage-svr"
    }
  }
}

MCPサーバーとして起動

# stdio transport（標準入出力での通信）
python mcp_server.py

提供されるツール

1. speak - 音声合成＆読み上げ

テキストを音声合成してキャラクターボイスで読み上げ
引数:
  - text: 読み上げるテキスト
  - speaker_name: 話者名（zundamon, tsumugi, metan）。省略時は自動選択
  - transform_tone: 口調変換の有無（デフォルト: true）

2. list_available_speakers - 話者一覧取得

利用可能な話者（キャラクター）の一覧を取得
戻り値: 話者情報のリスト（名前、スタイル、速度など）

3. transform_character_tone - 口調変換のみ

テキストをキャラクターの口調に変換（音声合成なし、文字列のみ）
引数:
  - text: 変換するテキスト
  - speaker_name: 話者名
戻り値: 元テキストと変換後テキスト

GitHub Copilot / Claude Desktop からの使用例

GitHub Copilot:

#yomiage タスクが完了しました、と読み上げて

Claude Desktop:

「処理が完了しました」をずんだもんの声で読み上げて

AIエージェントが自動的に適切なツールを呼び出し、音声で通知してくれます。

HTTPサーバーとMCPサーバーの使い分け

用途	推奨サーバー	起動方法
curl / Python から呼び出し	FastAPI HTTPサーバー	./start_server.sh
GitHub Copilot / Claude Desktop から呼び出し	MCPサーバー	.vscode/mcp.json で自動起動
常駐サーバーとして複数プロジェクトから利用	FastAPI HTTPサーバー	./start_server.sh

両方同時に起動することも可能です（ポートが異なるため競合しません）。

ライセンス・クレジット

VOICEVOX利用時は「VOICEVOX:ずんだもん」等のクレジット表記が必要です。
詳細は VOICEVOX利用規約 をご確認ください。