Connect Fish Audio TTS to RikkaHub

In RikkaHub, choose the Fish Audio speech provider and point the API base at Fish Audio instead of api.fish.audio. Then configure your API key, Voice ID, and model against /v1/tts.

After setup, RikkaHub speech requests consume your Fish Audio API credit balance and play audio through the selected Voice ID.

What you need

1. A Fish Audio account with API credits;
2. A Fish Audio API key;
3. A Fish Audio Voice ID (reference_id);
4. RikkaHub with the Fish Audio speech provider available.

An API key is a sensitive credential. Do not share it in chat, screenshots, or untrusted websites. Create a dedicated key for RikkaHub so you can monitor or revoke it separately.

Step 1: Create a Fish Audio API key

Sign in to Fish Audio, open API management, and create a key for RikkaHub. Copy and store it immediately because the complete key may only be shown once.

• Open API management
• Read the authentication guide
• View API pricing

Step 2: Find a Voice ID

RikkaHub sends the Voice ID as reference_id. Copy one from your Fish Audio voice list or query the API:

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

To test the connection immediately, start with this public system voice ID:

00a1b221-6137-4b73-ad62-b0cbce134167

Replace it with your preferred Voice ID after RikkaHub can generate and play audio successfully.

Do not confuse model and voice:

• The model header selects the TTS engine version;

• reference_id selects the speaker voice.

• List available voices

• Create a custom voice

Step 3: Configure the Fish Audio provider in RikkaHub

In RikkaHub, open the Fish Audio / TTS provider settings and enter:

Use whichever field names your RikkaHub build shows. The important part is that the request reaches POST https://fishaudio.org/v1/tts with:

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

and a JSON body that includes text plus a non-empty reference_id.

If RikkaHub pre-fills https://api.fish.audio, replace the host with https://fishaudio.org and keep /v1/tts.

Save the provider, generate one short sentence, and confirm that RikkaHub can play the returned audio.

Step 4: Assign the voice where needed

If RikkaHub lets you pick a voice per character, chat, or assistant, paste the same Fish Audio Voice ID into that field. You can reuse one provider configuration and only change reference_id per character.

API credit usage

RikkaHub calls Fish Audio /v1/tts and consumes the separate API credit balance. Text-to-speech starts at 1 API credit per effective character, and some models may apply a multiplier.

Purchase credits from API pricing and view the balance in API management. Successful responses may include X-OpenAPI-Credits-Used.

Troubleshooting and FAQ

RikkaHub reports a connection failure

Confirm the host is https://fishaudio.org, remove whitespace from the API key, and verify that the account still has API credits. Do not enter your Fish Audio account password.

The request returns 400 and mentions reference_id

Fish Audio requires an explicit Voice ID. Enter a valid reference_id; the server will not silently pick a default voice.

The request returns 401 or says the API key is invalid

Copy the Fish Audio API key again. If it was revoked, create a new key and replace the credential stored in RikkaHub.

The request returns 402 or says the balance is insufficient

Your API credit balance is too low. Membership credits and API credits are separate balances, so purchase API credits from the API pricing page.

RikkaHub connects but does not play audio

Test with mp3 first. If the client requested opus, Fish Audio falls back to mp3 so common Android players can decode the response. Also confirm the Voice ID is valid and that RikkaHub autoplay or mute settings are not blocking playback.

Which model should I choose?

Start with s2.1-pro or s2.1-pro-flash. Fish Audio maps these fish.audio labels to the matching engine model ids. Native ids such as fishaudio-s21pro-flash also work in the model header.

Related documentation

• Fish Audio Compatible TTS
• API authentication
• List voices
• API errors