# Speech Generation

> 文生语音工具，将文字转换为语音文件。原生 TTS 端点优先，失败自动降级为 chat completions（适配 MiMo/kokoro 等非标准 TTS 模型）。支持多种语音风格和音频格式。

- Skill: `kesepain-ke/speech-generation` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add kesepain-ke/speech-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kesepain-ke/speech-generation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kesepain-ke (https://skillmd.com/u/kesepain-ke)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kesepain-ke/speech-generation

---


# 文生语音 (Speech Generation)

将文字转换为自然语音文件并保存到本地。支持多种语音风格和音频格式。

## 插件路径

`plugins/speech_generation/`

## 工作方式

1. **原生 TTS 端点** → `client.audio.speech.create()`（OpenAI tts-1 / tts-1-hd）
2. 失败时自动降级为 **chat completions** → 文字作为用户消息发给专用模型，从响应中提取 base64 音频（支持 JSON 字段和裸 base64）

## 模型优先级

`speech_generation_model`（config.json 专用配置）> `"tts-1"`（默认）

配置后优先使用专用模型（如 `"hexgrad/kokoro-82m"`）；不配则使用 tts-1 走原生端点。

## 注册工具

| 工具名 | 描述 |
|--------|------|
| `speech_generate` | 将文字转换为语音文件并保存到本地 |

## 参数

| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `text` | string | 是 | — | 要转换的文字（最大 4096 字符） |
| `voice` | string | 否 | `"alloy"` | 语音风格/音色 ID。不同厂商音色完全不同，请根据当前 provider 配置的 TTS 模型选择对应音色 |
| `format` | string | 否 | `"mp3"` | 输出音频格式。常见值：mp3/opus/aac/flac/wav/pcm。具体取决于厂商支持 |
| `speed` | float | 否 | 1.0 | 语速倍率，通常 0.25-4.0，具体取决于厂商 |
| `output_dir` | string | 否 | `users/<user>/download/` | 输出目录 |

## 常见厂商音色参考

| 厂商 | 音色 ID 示例 |
|------|-------------|
| OpenAI | alloy / echo / fable / onyx / nova / shimmer |
| StepFun | ruanmengnvsheng / tianmeinvsheng / qingnianluoli / 等 |
| 其他厂商 | 请查阅厂商文档获取音色 ID 列表 |

## 结果说明

- 成功：返回保存后的本地文件路径
- chat 降级：从响应中提取 base64 音频并解码保存；无法解析时保存原始响应到 `.txt` 供排查
- 失败：返回 `ERROR:` 前缀的错误信息

## 支持的服务商

- **OpenAI 官方** — 原生 TTS 端点（tts-1 / tts-1-hd）
- **OpenRouter** — 配 `speech_generation_model` 后通过 chat 降级调用（如 `hexgrad/kokoro-82m`）
- **其他兼容厂商** — 配专用模型后自动降级到 chat completions
- **不支持时** — 可通过 `capabilities_override: ["speech_generation"]` 显式开启

## 典型场景

- 聊天回复转语音朗读
- 文字内容配音
- 通知/提醒语音播报

## 常见规范

- 输出目录默认为 `users/<user>/download/`
- 文字超过 4096 字符时可能被截断，长文本应分段处理
- 不同厂商的音色 ID 体系完全不同，不可混用

## 常见处理办法

- **音色无效**：检查当前 provider 配置的 TTS 模型，查阅厂商文档获取正确音色 ID
- **chat 降级无音频**：保存原始响应为 `.txt`，检查模型是否实际支持语音输出
- **格式不支持**：切换为常见格式 `mp3`，部分厂商仅支持少数格式

## 常见教训

- 非标准 TTS 模型（如 kokoro）的 `voice` 参数可能无效，会自动映射到默认音色
- chat 降级路径的响应格式因厂商而异，可能是 JSON 含 base64 字段，也可能是裸 base64
- `speed` 参数的可用范围因厂商而异，超范围可能被静默截断或报错