语音与 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

配置

# In ~/.hermes/config.yaml
tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "minimax" | "neutts"
  edge:
    voice: "en-US-AriaNeural"   # 322 voices, 74 languages
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"  # Adam
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  # Override for OpenAI-compatible TTS endpoints
  minimax:
    model: "speech-2.8-hd"     # speech-2.8-hd (default), speech-2.8-turbo
    voice_id: "English_Graceful_Lady"  # See 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 上发送的语音消息将被自动转录，并作为文本注入到对话中。该代理会将转录文本视为普通文本处理。

提供者	质量	成本	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 设置自定义命令。

配置

# In ~/.hermes/config.yaml
stt:
  provider: "local"           # "local" | "groq" | "openai" | "mistral"
  local:
    model: "base"             # tiny, base, small, medium, large-v3
  openai:
    model: "whisper-1"        # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe
  mistral:
    model: "voxtral-mini-latest"  # voxtral-mini-latest, 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）​

配置​

提供者详情​

回退行为​