Moss Tts Voice

---
name: moss-tts-voice
description: |
  MOSS-TTS 语音合成与音色克隆工具。生成适合各渠道的音频文件。
  
  触发场景：
  - 用户要求生成语音、TTS
  - 用户提到"用我的声音"、"克隆声音"、"MOSS语音"
  - 需要生成语音文件用于发送
  
  功能：文本转语音、实时克隆、预注册音色、多格式输出
metadata:
  openclaw:
    requires:
      env:
        - MOSS_API_KEY
      bins:
        - python3
        - ffmpeg
    primaryEnv: MOSS_API_KEY
    homepage: https://studio.mosi.cn
    emoji: "🎙️"
---

# MOSS-TTS 语音合成

> ⚠️ **注意**：本工具负责生成音频文件，发送到各渠道需要配合其他工具（如 OpenClaw message 工具）

## 快速开始（3 步）

### 1. 获取 API Key

访问 https://studio.mosi.cn → 注册/登录 → 控制台 → API 密钥 → 创建

```bash
export MOSS_API_KEY="sk-你的密钥"
```

### 2. 安装依赖

```bash
# 系统依赖
brew install python3 ffmpeg

# Python 依赖
pip3 install requests
```

### 3. 生成语音

```bash
python3 scripts/tts.py \
  --text "你好，我是MOSS" \
  --channel feishu \
  --json
```

输出：
```json
{
  "success": true,
  "file": "/tmp/openclaw/moss-tts/voice-xxx.ogg",
  "format": "ogg"
}
```

---

## ⚠️ 隐私与安全

### API Key 安全

- **不要提交到 Git**：将 `MOSS_API_KEY` 添加到 `.gitignore`
- **使用环境变量**：不要在代码中硬编码密钥
- **定期轮换**：建议定期更换 API Key

### 语音数据上传

- **克隆音色**：上传的音频会存储在 MOSS Studio 服务器
- **实时克隆**：每次请求都会上传音频数据到 MOSS API
- **数据保留**：参考 MOSS Studio 隐私政策

**建议**：
- 使用公开/非敏感音频进行克隆
- 避免上传包含敏感信息的录音
- 定期清理 MOSS Studio 中不需要的音色

---

## 功能说明

本工具提供以下功能：

1. **文本转语音** - 将文本转换为自然语音
2. **实时克隆** - 从音频即时克隆声音
3. **预注册音色** - 上传并保存音色供后续使用
4. **格式转换** - 自动转换为适合各渠道的格式

**不包含**：
- 直接发送到 IM 渠道（需要配合其他工具）
- 音色管理（删除、修改等）

---

## 使用模式

### 模式一：实时克隆

```bash
python3 scripts/tts.py \
  --text "要说的内容" \
  --reference_audio "参考音频.ogg" \
  --channel feishu
```

### 模式二：预注册音色（推荐）

```bash
# 1. 上传并克隆
curl -X POST https://studio.mosi.cn/api/v1/files/upload \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -F "file=@voice.ogg"
# → {"file_id": "YOUR_FILE_ID"}

curl -X POST https://studio.mosi.cn/api/v1/voice/clone \
  -H "Authorization: Bearer $MOSS_API_KEY" \
  -d '{"file_id": "YOUR_FILE_ID", "name": "我的声音"}'
# → {"voice_id": "YOUR_VOICE_ID"}

# 2. 使用（等待 10 秒后）
python3 scripts/tts.py \
  --text "你好" \
  --voice_id "YOUR_VOICE_ID" \
  --channel feishu
```

---

## 输出格式

| 渠道 | 格式 | 说明 |
|------|------|------|
| feishu | ogg (opus) | 飞书语音消息格式 |
| telegram | ogg (opus) | Telegram 语音消息格式 |
| whatsapp | ogg (opus) | WhatsApp 语音消息格式 |
| discord | mp3 | Discord 文件格式 |
| signal | mp3 | Signal 文件格式 |
| slack | mp3 | Slack 文件格式 |

---

## 参数说明

| 参数 | 说明 | 必填 |
|------|------|------|
| `--text` | 待合成文本 | ✅ |
| `--reference_audio` | 参考音频（实时克隆） | 二选一 |
| `--voice_id` | 预注册音色 ID | 二选一 |
| `--channel` | 目标渠道 | ❌ |
| `--format` | 输出格式 | ❌ |
| `--output` | 输出路径 | ❌ |
| `--json` | JSON 输出 | ❌ |

---

## 音频要求

- **格式**: ogg, mp3, wav, m4a
- **时长**: 10-30 秒（推荐 20 秒以上）
- **音质**: 清晰人声，无背景噪音
- **大小**: < 10MB

---

## 常见问题

### Q: 如何发送生成的语音？

本工具只生成音频文件。发送需要：
1. 使用返回的文件路径
2. 配合 OpenClaw message 工具或其他方式发送

### Q: 飞书发送后是文件而不是语音？

确保音频格式正确：
```bash
file voice.ogg
# 应显示: Ogg data, Opus audio
```

### Q: 克隆效果不好？

- 时长 20 秒以上
- 清晰人声，无噪音
- 正常语速

---

## API 端点

| 用途 | 端点 |
|------|------|
| 文本转语音 | `POST /v1/audio/tts` |
| 上传文件 | `POST /api/v1/files/upload` |
| 克隆音色 | `POST /api/v1/voice/clone` |
| 查询音色 | `GET /api/v1/voices` |

---

## 详细文档

- [API 技术细节](references/api-guide.md)
- [渠道格式说明](references/channel-formats.md)
- [问题排查](references/troubleshooting.md)

---

_版本: 1.2.0 | 更新: 2026-03-10_