將 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 播放音訊。

你需要什麼

1、一個Fish Audio帳戶，擁有API積分；2. Fish Audio API 鑰匙一把； 3、一個Fish Audio語音ID（reference_id）；4. RikkaHub 與 Fish Audio 語音提供者可用。

API 金鑰是敏感憑證。不要在聊天、螢幕截圖或不受信任的網站中共享它。為RikkaHub建立專用金鑰，以便您可以單獨監控或撤銷它。

步驟1：建立Fish Audio API金鑰

登入Fish Audio，開啟API管理，為RikkaHub建立金鑰。立即複製並儲存它，因為完整的密鑰可能只會顯示一次。

第 2 步：尋找語音 ID

RikkaHub 傳送語音 ID 作為 reference_id。從您的 Fish Audio 語音清單中複製一個或查詢 API：

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

若要立即測試連接，請從此公共系統語音 ID 開始：

00a1b221-6137-4b73-ad62-b0cbce134167

待RikkaHub成功產生並播放音訊後，將其替換為您喜歡的語音ID。

不要混淆模型和聲音：

車型頭選擇TTS引擎版本；
reference_id 選擇揚聲器聲音。
列出可用聲音
建立自訂語音

步驟3：在RikkaHub中設定Fish Audio提供者

在RikkaHub中，開啟Fish Audio / TTS提供者設定並輸入：

RikkaHub設定	價值
API 基礎/端點主機	`https://fishaudio.org`
完整端點（如果需要）	`https://fishaudio.org/v1/tts`
API 鑰匙	您的 Fish Audio API 鑰匙
型號	`s2.1-pro` 或 `s2.1-pro-flash`
語音 / `reference_id`	`00a1b221-6137-4b73-ad62-b0cbce134167`（測試後更換）
格式	`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 主體。

如果RikkaHub預填https://api.fish.audio，則將主機替換為https://fishaudio.org並保留/v1/tts。

儲存provider，產生一小句，確認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 金鑰中的空格，並驗證該帳號是否仍具有 API 積分。不要輸入您的 Fish Audio 帳戶密碼。

要求返回 400 並提及 `reference_id`

Fish Audio 需要明確語音 ID。輸入有效的reference_id；伺服器不會默默地選擇預設語音。

請求回傳401或說API金鑰無效

再次複製 Fish Audio API 金鑰。如果被撤銷，則建立新金鑰並取代 RikkaHub 中儲存的憑證。

請求回傳402或說餘額不足

您的 API 信用餘額太低。會員積分和 API 積分是單獨的餘額，因此請從 API 定價頁面購買 API 積分。

RikkaHub 連接但不播放音頻

首先用 mp3 進行測試。如果用戶端要求 opus，Fish Audio 會回退到 mp3，以便普通 Android 播放器可以解碼回應。也要確認語音 ID 有效，且 RikkaHub 自動播放或靜音設定不會阻止播放。

我該選擇哪個型號？

以 s2.1-pro 或 s2.1-pro-flash 開頭。 Fish Audio 將這些fish.audio 標籤對應到相符的引擎模型ID。諸如 fishaudio-s21pro-flash 之類的本機 ID 也可以在 model 標頭中使用。

RikkaHub 接入指南