介绍
# Voice.ai Voices
## ✨ 功能特性
- **9 种语音角色** - 针对不同用例精心策划的声音 - **11 种语言** - 使用多语言模型进行多语言合成 - **流式模式** - 生成时实时输出音频 - **语音设计** - 使用 temperature 和 top_p 参数进行自定义 - **OpenClaw 集成** - 与 OpenClaw 内置的 TTS 配合使用
---
## ⚙️ 配置
将您的 API 密钥设置为环境变量：
```bash export VOICE_AI_API_KEY="your-api-key" ```
**获取您的 API 密钥：** [Voice.ai Dashboard](https://voice.ai/dashboard)
---
## 📦 安装
无需安装步骤。该技能包包含 Node.js CLI 和 SDK（无外部 npm 依赖项）。
## 🧩 关键文件
- [`scripts/tts.js`](scripts/tts.js) - CLI 入口点 - [`voice-ai-tts-sdk.js`](voice-ai-tts-sdk.js) - CLI 使用的 Node.js SDK - [`voices.json`](voices.json) - CLI 使用的语音定义 - [`voice-ai-tts.yaml`](voice-ai-tts.yaml) - API 规范 - [`package.json`](package.json) - 工具链使用的技能元数据
## 安全说明
完整的安全和隐私概述请参阅 [`SECURITY.md`](SECURITY.md)。
该技能： - 仅向 `https://dev.voice.ai` 发出出站 HTTPS 请求 - 读取本地文件：`voices.json` - 将音频输出写入 `--output` 路径（默认为 `output.mp3`） - 不执行 shell 命令，也不修改系统配置文件
## 🌐 API 端点
SDK 和规范使用 `https://dev.voice.ai`，这是 Voice.ai 官方的生产 API 域名。
---
## 🤖 OpenClaw 集成
如果您的环境暴露了 `VOICE_AI_API_KEY`，OpenClaw 可以直接调用 CLI 脚本。按照您的 OpenClaw 安装配置使用 `/tts` 命令。
---
## 📝 触发器
这些聊天命令适用于 OpenClaw：
| Command | Description | |---------|-------------| | `/tts <text>` | 使用默认语音生成语音 | | `/tts --voice ellie <text>` | 使用指定语音生成语音 | | `/tts --stream <text>` | 使用流式模式生成 | | `/voices` | 列出可用语音 |
**示例：**
``` /tts Hello, welcome to Voice.ai! /tts --voice oliver Good morning, everyone. /tts --voice lilith --stream This is a long story that will stream as it generates... ```
---
## 🎙️ 可用语音
| Voice | ID | Gender | Persona | Best For | |---------|-----|--------|-------------|----------------------------| | ellie | `d1bf0f33-8e0e-4fbf-acf8-45c3c6262513` | female | youthful | Vlogs, social content | | oliver | `f9e6a5eb-a7fd-4525-9e92-75125249c933` | male | british | Narration, tutorials | | lilith | `4388040c-8812-42f4-a264-f457a6b2b5b9` | female | soft | ASMR, calm content | | smooth | `dbb271df-db25-4225-abb0-5200ba1426bc` | male | deep | Documentaries, audiobooks | | shadow | `72d2a864-b236-402e-a166-a838ccc2c273` | male | distinctive | Gaming, entertainment | | sakura | `559d3b72-3e79-4f11-9b62-9ec702a6c057` | female | anime | Character voices | | zenith | `ed751d4d-e633-4bb0-8f5e-b5c8ddb04402` | male | deep | Gaming, dramatic content | | flora | `a931a6af-fb01-42f0-a8c0-bd14bc302bb1` | female | cheerful | Kids content, upbeat | | commander | `bd35e4e6-6283-46b9-86b6-7cfa3dd409b9` | male | heroic | Gaming, action content |
---
## 🌍 支持的语言
| Code | Language | |------|------------| | `en` | English | | `es` | Spanish | | `fr` | French | | `de` | German | | `it` | Italian | | `pt` | Portuguese | | `pl` | Polish | | `ru` | Russian | | `nl` | Dutch | | `sv` | Swedish | | `ca` | Catalan |
对于非英语语言，请使用多语言模型：
```javascript const audio = await client.generateSpeech({ text: 'Bonjour le monde!', voice_id: 'ellie-voice-id', model: 'voiceai-tts-multilingual-v1-latest', language: 'fr' }); ```
---
## 🎨 语音设计
使用以下参数自定义语音输出：
| Parameter | Range | Default | Description | |-----------|-------|---------|-------------| | `temperature` | 0-2 | 1.0 | 较高值 = 更具表现力，较低值 = 更加一致 | | `top_p` | 0-1 | 0.8 | 控制语音生成中的随机性 |
**示例：**
```javascript const audio = await client.generateSpeech({ text: 'This will sound very expressive!', voice_id: 'ellie-voice-id', temperature: 1.8, top_p: 0.9 }); ```
---
## 📡 流式模式
使用实时流式传输生成音频（推荐用于长文本）：
```bash # Stream audio as it generates node scripts/tts.js --text "This is a long story..." --voice ellie --stream
# Streaming with custom output node scripts/tts.js --text "Chapter one..." --voice oliver --stream --output chapter1.mp3 ```
**SDK 流式传输：**
```javascript const stream = await client.streamSpeech({ text: 'Long text here...', voice_id: 'ellie-voice-id' });
// Pipe to file stream.pipe(fs.createWriteStream('output.mp3'));
// Or handle chunks stream.on('data', chunk => { // Process audio chunk }); ```
---
## 🔊 音频格式
| Format | Description | Use Case | |--------|-------------|----------| | `mp3` | Standard MP3 (32kHz) | General use | | `wav` | Uncompressed WAV | High quality | | `pcm` | Raw PCM audio | Processing | | `opus_48000_128` | Opus 128kbps | Streaming | | `mp3_44100_192` | High-quality MP3 | Professional |
所有格式选项请参阅 `voice-ai-tts-sdk.js`。
---
## 💻 CLI 使用方法
```bash # Set API key export VOICE_AI_API_KEY="your-key-here"
# Generate speech node scripts/tts.js --text "Hello world!" --voice ellie
# Choose different voice node scripts/tts.js --text "Good morning!" --voice oliver --output morning.mp3
# Use streaming for long texts node scripts/tts.js --text "Once upon a time..." --voice lilith --stream
# Show help node scripts/tts.js --help ```
---
## 📁 文件
``` voice-ai-tts/ ├── SKILL.md # This documentation ├── README.md # Quick start ├── CHANGELOG.md # Version history ├── LICENSE.md # MIT license ├── SECURITY.md # Security & privacy notes ├── voices.json # Voice definitions ├── voice-ai-tts.yaml # OpenAPI specification ├── voice-ai-tts-sdk.js # JavaScript/Node.js SDK ├── package.json # OpenClaw metadata ├── scripts/ │ └── tts.js # CLI tool ```
---
## 💰 成本与使用
Voice.ai 使用基于积分的系统。检查您的使用情况：
```javascript // The SDK tracks usage via API responses const voices = await client.listVoices(); // Check response headers for rate limit info ```
**降低成本的提示：** - 对长文本使用流式传输（效率更高） - 尽可能缓存生成的音频 - 根据您的用例使用适当的音频质量
---
## 🔗 链接
- **[Get API Key](https://voice.ai/dashboard)** - 注册并获取您的密钥 - **[API Documentation](https://voice.ai/docs)** - 完整的 API 参考 - **[Voice Library](https://voice.ai/voices)** - 浏览所有语音 - **[API Reference](https://voice.ai/docs/api-reference/text-to-speech/generate-speech)** - 端点详情 - **[Pricing](https://voice.ai/pricing)** - 计划和积分
---
## 📋 更新日志
### v1.1.5 (2026-02-16) - 通过 `metadata.clawdbot` 声明运行时要求，以便 ClawHub 显示所需的环境变量
### v1.1.4 (2026-02-16) - 在元数据中将 `VOICE_AI_API_KEY` 声明为主要环境变量
### v1.1.3 (2026-02-16) - 从已发布的包中移除了语音样本上传功能，以降低隐私风险 - 仅通过环境变量要求 `VOICE_AI_API_KEY`
### v1.1.2 (2026-02-16) - 添加了 `SECURITY.md` 和 `LICENSE.md` 以实现来源透明 - 限制 SDK 传输仅使用 HTTPS
### v1.1.1 (2026-02-16) - 针对 ClawHub 导入改进了打包元数据（bin/files 元数据）
### v1.1.0 (2026-02-16) - 在元数据中声明了所需凭证 - 记录了生产 API 端点域名 - 重命名了语音角色以实现 IP 安全标记 - 添加了 `voices.json` 用于语音数据
### v1.0.0 (2025-01-31) - 初始版本 - 9 种精选语音角色 - 11 种语言支持 - 流式模式 - 语音设计参数 - 包含错误处理的完整 SDK - CLI 工具
---
## 🛠️ SDK 快速参考
```javascript const VoiceAI = require('./voice-ai-tts-sdk'); const client = new VoiceAI(process.env.VOICE_AI_API_KEY);
// List voices const voices = await client.listVoices({ limit: 10 });
// Get voice details const voice = await client.getVoice('voice-id');
// Generate speech const audio = await client.generateSpeech({ text: 'Hello, world!', voice_id: 'voice-id', audio_format: 'mp3' });
// Generate to file await client.generateSpeechToFile( { text: 'Hello!', voice_id: 'voice-id' }, 'output.mp3' );
// Stream speech const stream = await client.streamSpeech({ text: 'Long text...', voice_id: 'voice-id' });
// Delete voice await client.deleteVoice('voice-id'); ```
---
## ❓ 故障排除
| Error | Cause | Solution | |-------|-------|----------| | `AuthenticationError` | Invalid API key | 检查您的 `VOICE_AI_API_KEY` | | `PaymentRequiredError` | Out of credits | 在 voice.ai/dashboard 添加积分 | | `RateLimitError` | Too many requests | 等待并重试，或升级计划 | | `ValidationError` | Invalid parameters | 检查文本长度和 voice_id |
---
Made with ❤️ by [Nick Gill](https://github.com/gizmoGremlin)