語音與 TTS

Hermes Agent 支持在所有消息平臺上的文本轉語音輸出以及語音消息轉錄。

文本轉語音（TTS）

通過五種提供者實現文本轉語音：

提供者	質量	成本	API 密鑰
Edge TTS（默認）	良好	免費	無需
ElevenLabs	優秀	付費	`ELEVENLABS_API_KEY`
OpenAI TTS	良好	付費	`VOICE_TOOLS_OPENAI_KEY`
MiniMax TTS	優秀	付費	`MINIMAX_API_KEY`
NeuTTS	良好	免費	無需

平臺交付方式

平臺	交付方式	格式
Telegram	語音氣泡（內聯播放）	Opus `.ogg`
Discord	語音氣泡（Opus/OGG），降級為文件附件	Opus/MP3
WhatsApp	音頻文件附件	MP3
CLI	保存至 `~/.hermes/audio_cache/`	MP3

配置

# 在“0”中
tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "minimax" | "neutts"
  edge:
    voice: "en-US-AriaNeural"   # 322 種聲音，74 種語言
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"  # 亞當
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # 合金、回聲、寓言、縞瑪瑙、新星、微光
    base_url: "https://api.openai.com/v1"  # 覆蓋 OpenAI 兼容的 TTS 端點
  minimax:
    model: "speech-2.8-hd"     # 語音 2.8-hd（默認）、語音 2.8-turbo
    voice_id: "English_Graceful_Lady"  # 參見 https://platform.minimax.io/faq/system-voice-id
    speed: 1                    # 0.5 - 2.0
    vol: 1                      # 0 - 10
    pitch: 0                    # -12 - 12
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

Telegram 語音氣泡與 ffmpeg

Telegram 語音氣泡需要 Opus/OGG 音頻格式：

OpenAI 和 ElevenLabs 原生輸出 Opus —— 無需額外配置
Edge TTS（默認）輸出 MP3，需要 ffmpeg 進行轉換
MiniMax TTS 輸出 MP3，需要 ffmpeg 轉換為 Telegram 語音氣泡格式
NeuTTS 輸出 WAV，同樣需要 ffmpeg 轉換為 Telegram 語音氣泡格式

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Fedora
sudo dnf install ffmpeg

若未安裝 ffmpeg，Edge TTS、MiniMax TTS 和 NeuTTS 的音頻將以普通音頻文件形式發送（可播放，但顯示為矩形播放器而非語音氣泡）。

提示

若不想安裝 ffmpeg，可切換至 OpenAI 或 ElevenLabs 提供者以獲得語音氣泡。

語音消息轉錄（STT）

在 Telegram、Discord、WhatsApp、Slack 或 Signal 上發送的語音消息將被自動轉錄，並作為文本注入到對話中。該 Agent 會將轉錄文本視為普通文本處理。

提供者	質量	成本	API 密鑰
本地 Whisper（默認）	良好	免費	無需
Groq Whisper API	良好–最佳	免費套餐	`GROQ_API_KEY`
OpenAI Whisper API	良好–最佳	付費	`VOICE_TOOLS_OPENAI_KEY` 或 `OPENAI_API_KEY`

零配置

當安裝了 faster-whisper 時，本地轉錄可開箱即用。若不可用，Hermes 也可使用常見安裝路徑（如 /opt/homebrew/bin）中的本地 whisper CLI，或通過 HERMES_LOCAL_STT_COMMAND 設置自定義命令。

配置

# 在“0”中
stt:
  provider: "local"           # "local" | "groq" | "openai" | "mistral"
  local:
    model: "base"             # 微小、基礎、小型、中型、大型-v3
  openai:
    model: "whisper-1"        # 耳語-1、gpt-4o-迷你轉錄、gpt-4o-轉錄
  mistral:
    model: "voxtral-mini-latest"  # voxtral-mini-最新，voxtral-mini-2602

提供者詳情

本地（faster-whisper） —— 通過 faster-whisper 在本地運行 Whisper。默認使用 CPU，若有 GPU 則使用 GPU。模型大小如下：

模型	大小	速度	質量
`tiny`	~75 MB	最快	基礎
`base`	~150 MB	快	良好（默認）
`small`	~500 MB	中等	更好
`medium`	~1.5 GB	較慢	優秀
`large-v3`	~3 GB	最慢	最佳

Groq API —— 需要 GROQ_API_KEY。當希望使用免費託管 STT 選項時，是良好的雲端備用方案。

OpenAI API —— 優先接受 VOICE_TOOLS_OPENAI_KEY，若未設置則回退至 OPENAI_API_KEY。支持 whisper-1、gpt-4o-mini-transcribe 和 gpt-4o-transcribe。

Mistral API（Voxtral Transcribe） —— 需要 MISTRAL_API_KEY。使用 Mistral 的 Voxtral Transcribe 模型。支持 13 種語言、說話人分離和詞級時間戳。通過 pip install hermes-agent[mistral] 安裝。

自定義本地 CLI 備用方案 —— 若希望 Hermes 直接調用本地轉錄命令，可設置 HERMES_LOCAL_STT_COMMAND。命令模板支持 {input_path}、{output_dir}、{language} 和 {model} 佔位符。

回退行為

若配置的提供者不可用，Hermes 會自動回退：

本地 faster-whisper 不可用 → 嘗試本地 whisper CLI 或 HERMES_LOCAL_STT_COMMAND，再回退至雲端提供者
Groq 密鑰未設置 → 回退至本地轉錄，再嘗試 OpenAI
OpenAI 密鑰未設置 → 回退至本地轉錄，再嘗試 Groq
Mistral 密鑰/SDK 未設置 → 自動檢測中跳過，繼續嘗試下一個可用提供者
均不可用 → 語音消息將原樣傳遞，並向用戶附帶準確說明

文本轉語音（TTS）​

平臺交付方式​

配置​

Telegram 語音氣泡與 ffmpeg​

語音消息轉錄（STT）​

配置​

提供者詳情​

回退行為​