Nijivoice

🚀 NijiVoice-MCP 項目文檔

NijiVoice-MCP 實現了 にじボイス API 的 Model Context Protocol (MCP) 版本。藉助該項目，大語言模型（LLM）能夠訪問 NijiVoice API，輕鬆實現文本到語音的轉換，為語音合成應用提供了便利。

🚀 快速開始

本項目處於開發階段，尚未經過全面驗證，請勿在生產環境中使用！

系統要求

• Python 3.12 或更高版本
• NijiVoice API Key
• 網絡連接

安裝指南

# 克隆代碼倉庫
git clone https://github.com/YOUR_USERNAME/nijivoice-mcp.git
cd nijivoice-mcp

# 安裝依賴包
pip install -e .

環境配置

1. 創建 .env 文件，添加以下內容：

NIJIVOICE_API_KEY=你的API密鑰
DEFAULT_VOICE_ACTOR_ID=默認使用的聲優ID（可選）
LOG_LEVEL=INFO

2. API Key 可在 NijiVoice 官網獲取。

啟動 MCP 服務器

python main.py

啟動後，MCP 服務器將開始監聽來自 LLM 的請求。

✨ 主要特性

• 使用 NijiVoice API 進行語音合成
• 獲取可用聲優信息
• 查詢剩餘話費
• 通過 MCP 接口與 LLM 對接

💻 使用示例

基礎用法

LLM 端調用 MCP 服務：

# 獲取可用聲優列表
actors = await tools.call("actor/get_voice_actors")

# 合成語音
voice_result = await tools.call("voice/generate_voice", {
    "script": "你好，這是 NijiVoice 的測試。",
    "voice_actor_id": "90031163-c497-44f3-a8a6-e45e4d0cb8f6",  # 聲優ID
    "speed": 1.0,
    "emotional_level": 0.5,
    "sound_duration": 0.1,
    "format": "mp3"
})

# 查詢剩餘話費
balance = await tools.call("credit/get_credit_balance")

📚 詳細文檔

可用的 MCP 工具

聲優相關工具

• actor/get_voice_actors(): 獲取所有可用聲優信息。

語音合成工具

• voice/generate_voice(): 將文本轉換為語音。

項目結構

nijivoice-mcp/
├── niji_mcp/
│   ├── __init__.py
│   ├── api.py          # API 客戶端實現
│   ├── exceptions.py   # 異常定義
│   └── models.py       # 數據模型
├── server.py           # MCP 服務器實現
└── utils/              # 工具函數
    ├── __init__.py
    ├── audio_utils.py   # 音頻處理工具
    ├── error_handling.py# 錯誤處理邏輯
    └── retry_logic.py   # 重試機制

測試

# 執行測試
pytest

🔧 技術細節

注意事項與已知問題

1. 開發中項目：功能和規格可能隨時變更。
2. NijiVoice API 變更風險：若其 API 更新，可能導致本項目不兼容。
3. 錯誤處理不足：某些錯誤場景的處理尚未完善。
4. 長文本生成超時：處理長文本時有可能發生超時。
5. 部分響應格式未適配：未能完全支持 NijiVoice 的所有 API 響應格式。

故障排除

遇到問題時，可按以下步驟排查：

1. 查看日誌文件 nijivoice_mcp.log
2. 確認 API Key 是否正確配置
3. 檢查網絡連接狀態
4. 查看 NijiVoice API 的運行狀況

📄 許可證

本項目遵循 MIT License 協議。

致謝

感謝參考了 FastMCP 和 Model Context Protocol，並使用 NijiVoice 的語音合成技術。