将 RikkaHub 的 Fish Audio 提供商指向 Fish Audio 兼容的 /v1/tts 接口，并配置音色 ID 与模型。

将 Fish Audio TTS 接入 RikkaHub

在 RikkaHub 中选择 Fish Audio 语音提供商，把 API Base 从 api.fish.audio 改成 Fish Audio，再配置 API Key、音色 ID 与模型（使用 /v1/tts）。

配置完成后，RikkaHub 的语音请求会消耗你的 Fish Audio API 积分余额，并按所选音色 ID 播放。

你需要准备

有 API 积分的 Fish Audio 账号；
一个 Fish Audio API Key；
一个 Fish Audio 音色 ID（reference_id）；
已提供 Fish Audio 语音提供商选项的 RikkaHub。

API Key 属于敏感凭据。不要把它发到聊天、截图或不可信网站。建议为 RikkaHub 单独创建 Key，便于监控与吊销。

步骤 1：创建 Fish Audio API Key

步骤 2：找到音色 ID

RikkaHub 会把音色 ID 作为 reference_id 发送。可从 Fish Audio 音色列表复制，或调用：

GET /api/open/v1/voices
Authorization: Bearer YOUR_API_KEY

联调时可先用这个公共系统音色 ID：

00a1b221-6137-4b73-ad62-b0cbce134167

确认 RikkaHub 能生成并播放音频后，再换成你真正要用的音色 ID。

不要把模型和音色搞混：

model 请求头选择 TTS 引擎版本；
reference_id 选择说话音色。
列出可用音色
创建自定义音色

步骤 3：在 RikkaHub 配置 Fish Audio 提供商

在 RikkaHub 打开 Fish Audio / TTS 提供商设置，填写：

RikkaHub 设置	值
API Base / 服务地址	`https://fishaudio.org`
完整接口（若应用要求填全路径）	`https://fishaudio.org/v1/tts`
API Key	你的 Fish Audio API Key
Model	`s2.1-pro` 或 `s2.1-pro-flash`
Voice / `reference_id`	`00a1b221-6137-4b73-ad62-b0cbce134167`（联调通过后替换）
Format	`mp3`

不同 RikkaHub 版本字段名可能略有差异。关键是请求最终要打到 POST https://fishaudio.org/v1/tts，并带有：

Authorization: Bearer YOUR_API_KEY
model: s2.1-pro
Content-Type: application/json

以及包含 text 与非空 reference_id 的 JSON body。

如果 RikkaHub 预填了 https://api.fish.audio，把主机改成 https://fishaudio.org，并保留 /v1/tts。

保存提供商后，先生成一句短文本，确认 RikkaHub 能播放返回的音频。

步骤 4：按角色绑定音色（如有）

如果 RikkaHub 支持按角色 / 会话 / 助手选择音色，把同一个 Fish Audio 音色 ID 填到对应字段即可。你可以复用同一套提供商配置，只改每个角色的 reference_id。

API 积分消耗

RikkaHub 调用的是 Fish Audio /v1/tts，会消耗独立的 API 积分余额。文本转语音从每有效字符 1 API 积分起计，部分模型可能有倍率。

可在 API 定价购买积分，并在 API 管理中查看余额。成功响应可能会返回 X-OpenAPI-Credits-Used。

故障排查与常见问题

RikkaHub 提示连接失败

确认主机是 https://fishaudio.org，API Key 前后没有空格，且账号仍有 API 积分。不要填写 Fish Audio 账号密码。

返回 400，并提到 `reference_id`

Fish Audio 要求显式音色 ID。请填写有效的 reference_id；服务端不会静默选择默认音色。

返回 401，或提示 API Key 无效

重新复制 Fish Audio API Key。若 Key 已吊销，请新建后替换 RikkaHub 中保存的凭据。

返回 402，或提示余额不足

API 积分不足。会员积分与 API 积分是分开的，请到 API 定价页购买 API 积分。

能连通但播不出声音

先用 mp3 测试。若客户端请求了 opus，Fish Audio 会降级为 mp3，方便常见 Android 播放器解码。同时确认音色 ID 有效，以及 RikkaHub 没有静音 / 关闭自动播放。

应该选哪个模型？

建议先用 s2.1-pro 或 s2.1-pro-flash。Fish Audio 会把这些 fish.audio 标签映射到对应引擎模型。model 请求头也可以直接填原生 ID，例如 fishaudio-s21pro-flash。

RikkaHub 接入指南