Connect Fish Audio TTS to Home Assistant

This guide uses the HACS OpenAI TTS integration that supports custom OpenAI-compatible endpoints. It sends Fish Audio speech to Home Assistant media players for announcements, automations, and Assist.

Install the integration

1. Open HACS and search Integrations for OpenAI TTS.
2. Download it and restart Home Assistant.
3. Open Settings → Devices & Services → Add Integration → OpenAI TTS.
4. Enter your Fish Audio API key and custom endpoint https://fishaudio.org/v1.

Add a TTS agent with:

Custom endpoint mode accepts a manually entered Fish Audio Voice ID. Replace the test voice after the first successful announcement.

Test an announcement

Call the integration's openai_tts.say action from Developer Tools:

action: openai_tts.say
target:
  entity_id: media_player.living_room_speaker
data:
  tts_entity: tts.openai_tts_fish_audio
  message: 'Hello, this is a Fish Audio smart-home announcement.'
  volume: 0.6

Replace both entity IDs with your actual TTS agent and media player. After it works, reuse the action in doorbell, alert, weather, or calendar automations.

Troubleshooting

• No custom endpoint field: make sure you installed the HACS OpenAI TTS integration, not built-in OpenAI Conversation.
• The speaker is silent: confirm that the media_player can play regular media and inspect Home Assistant logs.
• Fish Audio voices are not listed: manually enter the Voice ID in custom endpoint mode.
• 401/402: verify the API key and API credit balance.

Related documentation

• API pricing
• Find a Voice ID
• HACS OpenAI TTS project
• Official Home Assistant Fish Audio integration