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 的语音合成技术。