RimTalk TTS 接入教程
在 RimWorld 非官方模组 RimTalk TTS 中添加 Fish Audio OpenAI 兼容供应商，并为不同殖民者绑定独立音色。
在 RimTalk TTS 中接入 Fish Audio
RimTalk TTS 可以通过自定义 OpenAI 兼容供应商调用 Fish Audio，让 RimWorld 中不同殖民者使用指定音色朗读对话。
先确认 RimTalk 版本
本教程要求 RimTalk TTS 设置页中已经出现“自定义 TTS 供应商（未经测试！）”和“添加新自定义供应商”。该功能目前属于上游项目的开发版本；如果你的设置页没有这些选项，请先确认所安装模组的来源和版本，不要把下面的地址填入旧版内置 Fish Audio 供应商。
开始前需要准备
- 可用的 API 积分；
- 一个专门用于 RimTalk 的 API Key；
- 至少一个 Fish Audio 音色 ID；
- 带有自定义 TTS 供应商功能的 RimTalk TTS。
API Key 是敏感凭证。建议为每位客户或每台设备创建独立 Key，以便单独监控和撤销。不要把完整 Key 放进公开截图、聊天记录、模组压缩包或 Steam 创意工坊内容中；如果 Key 已出现在截图里，应立即撤销并更换。
第一次联通测试可以使用系统测试音色：
00a1b221-6137-4b73-ad62-b0cbce134167添加自定义 TTS 供应商
在 RimTalk TTS 设置中找到：
TTS 配置 → 自定义 TTS 供应商 → 添加新自定义供应商填写以下基础设置：
| RimTalk 配置项 | 填写内容 |
|---|---|
| 供应商名称 | Fish Audio |
| 基础 URL | https://fishaudio.org/v1 |
| 接口路径 | /audio/speech |
| 模型 | fishaudio-s21pro-flash |
| 默认音色 | 00a1b221-6137-4b73-ad62-b0cbce134167（测试后可替换） |
| 响应格式 | mp3 |
页面显示的完整 URL 应为：
https://fishaudio.org/v1/audio/speech模型必须填写 fishaudio-s21pro-flash 等 Fish Audio 公共模型 ID。不要填写 OpenAI 的 tts-1、默认音色名 alloy，也不要填写 RimTalk 内置 Fish Audio 供应商使用的 s2.1-pro。
配置认证和可选参数
在认证设置中填写：
| RimTalk 配置项 | 填写内容 |
|---|---|
| 需要 API 密钥 | 开启 |
| API 密钥 | 为本次 RimTalk 接入创建的独立 Key |
| 认证头名称 | Authorization |
| 认证头前缀 | Bearer 后再输入一个空格 |
认证头前缀的末尾空格不可省略。RimTalk 会把前缀与 API Key 直接拼接；缺少空格时会形成无效的 BearerYOUR_API_KEY。
建议的可选参数：
| 设置 | 建议值 |
|---|---|
| 发送 speed | 开启 |
| temperature | 关闭 |
| top_p | 关闭 |
| emotion/style | 关闭 |
| instruct_text | 关闭 |
| streaming | 关闭 |
| 自定义请求体模板 | 关闭 |
| 超时时间 | 60 秒 |
| 生成冷却 | 保留默认值 |
保存后，在语音服务供应商列表中选中刚创建的 Fish Audio 自定义供应商。
添加音色并分配给殖民者
供应商编辑窗口中的“默认音色”只负责初始请求。要让多个殖民者使用不同声音，还需要回到 RimTalk 的音色模型区域：
- 添加一个音色模型；
- 显示名称填写便于识别的名字，例如“男青年”或“女医生”；
- Model ID 填写 Fish Audio 音色 UUID，而不是音色名称；
- 选择一个音色作为默认音色；
- 在殖民者语音设置中，把不同 Pawn 分配给对应音色。
模型和音色是两个不同字段：fishaudio-s21pro-flash 决定 TTS 引擎，音色 UUID 决定最终声音。
测试接入
先只配置一个音色，并让一个殖民者朗读一句短文本。成功时，RimTalk 会向 /v1/audio/speech 发送 OpenAI 格式请求，并接收完整 MP3 音频后播放。
确认以下结果：
- RimTalk 日志中请求地址没有重复
/v1或/audio/speech； - 请求返回 HTTP
200； - 游戏中可以播放完整音频；
- API 页面出现对应的调用和积分消耗；
- 替换为正式音色 ID 后，不同殖民者使用正确音色。
RimTalk 当前等待同步音频响应，不会轮询异步任务。殖民者对话通常较短，适合使用同步接口；如果生成较长文本，请先缩短输入，而不是改用异步 Jobs 地址。
常见问题
- 401 或 API Key 无效：检查 Key 是否完整、是否已撤销，并确认认证头前缀是
Bearer加一个空格。 - 402 或额度不足：API 积分余额不足；会员积分与 API 积分不是同一余额。
- 404：基础 URL 只填写到
/v1，接口路径只填写/audio/speech，不要在两个字段中重复路径。 - 400 或模型无效：模型使用
fishaudio-s21pro-flash，不要使用tts-1或s2.1-pro。 - 音色无效：Model ID 必须填写音色 UUID，不要填写显示名称或模型 ID。
- 30 秒后超时：把 RimTalk 超时调整为
60秒，使用fishaudio-s21pro-flash并先测试短句。 - 请求成功但没有声音：确认已选中自定义供应商、默认音色不是
NONE，并检查殖民者的音色绑定和游戏音量。 - 429：保留生成冷却，不要让大量殖民者同时高频触发语音；稍后重试。