picoclaw/pkg/audio/tts/README.zh.md

TTS（文本转语音）

这个目录负责 PicoClaw 的语音合成能力。

如果你是第一次配置 TTS，可以参照下面这个流程：

1. 在 model_list 里添加一个支持 TTS 的模型。
2. 用 voice.tts_model_name 指向这个模型。
3. 在 .security.yml 里配置对应的 API Key。

快速推荐

对于大多数用户，建议优先从下面两种开始：

提供商	推荐理由
OpenAI	这是 PicoClaw 当前最稳定、最直接的 TTS 路径。当前实现就是围绕 OpenAI 兼容的 /audio/speech 接口格式构建的，所以 OpenAI 是最稳妥的默认选择。
Xiaomi MiMo	由于响应速度和语音音色对于中国用户更友好，MiMo 是一个不错的第二选择。

TTS 配置是如何工作的

PicoClaw 不会把 TTS 的 API Key 放在 voice 配置里。

推荐方式是：

• voice.tts_model_name 用来选择 model_list 里的某个命名模型。
• 对应的 model_list 条目提供真实的 provider、model ID、api_base 和代理配置。
• .security.yml 负责保存该模型条目的 API Key。

这是当前推荐且受支持的配置方式。

推荐配置方式

方案 A：OpenAI

config.json

{
  "voice": {
    "tts_model_name": "openai-tts"
  },
  "model_list": [
    {
      "model_name": "openai-tts",
      "model": "openai/tts-1"
    }
  ]
}

.security.yml

model_list:
  openai-tts:
    api_keys:
      - "sk-openai-your-key"

方案 B：Xiaomi MiMo

config.json

{
  "voice": {
    "tts_model_name": "mimo-tts"
  },
  "model_list": [
    {
      "model_name": "mimo-tts",
      "model": "mimo/mimo-v2-tts"
    }
  ]
}

.security.yml

model_list:
  mimo-tts:
    api_keys:
      - "your-mimo-key"

如果你使用自定义的 MiMo 接口地址，也可以显式设置 api_base。如果不设置，PicoClaw 会自动使用该 provider 的默认地址。

PicoClaw 当前实际发送的 TTS 请求

当前 TTS 运行时使用的是 OpenAI 兼容的语音合成请求，并带有以下默认值：

• Endpoint：/audio/speech
• 返回格式：opus
• Voice：alloy
• Model：来自你所选中的 model_list 条目

这意味着：

• openai/tts-1 可以自然工作。
• 其他 OpenAI 兼容 provider 也可能可用，前提是它们接受相同的请求格式。
• PicoClaw 目前还没有对用户暴露一个配置项来修改 TTS voice，当前固定为 alloy。

PicoClaw 如何选择 TTS Provider

DetectTTS 会按下面顺序选择 TTS：

1. 首选路径：根据 voice.tts_model_name 在 model_list 中找到对应模型。
2. 如果找到了匹配条目，并且它有 API Key，PicoClaw 就会使用这个模型条目的配置创建一个 OpenAI 兼容的 TTS provider。
3. 回退路径：如果没有设置 voice.tts_model_name，或者该名字无法解析，PicoClaw 会扫描 model_list，选中第一个模型字符串里包含 tts 且带有 API Key 的条目。

回退扫描只是为了兼容旧行为。新配置建议始终显式设置 voice.tts_model_name。

关于 API Base 的处理方式

PicoClaw 会对 TTS 的 api_base 做规范化处理：

• 对 OpenAI 来说，像 https://api.openai.com 或 https://api.openai.com/v1 这样的地址，会自动变成 https://api.openai.com/v1/audio/speech。
• 对其他 OpenAI 兼容 provider，PicoClaw 会尽量保留你提供的基础路径，只确保它最终以 /audio/speech 结尾。
• 如果没有设置 api_base，并且模型前缀是已知 provider，PicoClaw 会自动使用该 provider 的默认地址。

常见错误

• voice.tts_model_name 指向了一个不存在的 model_list 名称。
• 在 model_list 里定义了 TTS 模型，但忘了在 .security.yml 中配置对应 API Key。
• 误以为 PicoClaw 会自动支持 provider 自定义 voice 参数。
• 使用了不兼容 OpenAI /audio/speech 请求格式的接口地址。

最小检查清单

在测试 send_tts 之前，请确认：

• voice.tts_model_name 能正确匹配某个 model_list[].model_name。
• .security.yml 中对应条目已经配置了有效 API Key。
• 你所选的 provider 支持 OpenAI 兼容的语音合成接口。
• 你选择的模型本身确实支持 TTS。