语音与语音合成（TTS）

Hermes Agent 支持所有消息平台的文本转语音输出以及语音消息转录功能。

文本转语音（TTS）

支持六种语音合成服务，可将文本转换为语音：

服务提供商	音质	成本	API 密钥
Edge TTS（默认）	良好	免费	不需要
ElevenLabs	极佳	付费	ELEVENLABS_API_KEY
OpenAI TTS	良好	付费	VOICE_TOOLS_OPENAI_KEY
MiniMax TTS	极佳	付费	MINIMAX_API_KEY
Mistral（Voxtral TTS）	极佳	付费	MISTRAL_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" | "mistral" | "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
  mistral:
    model: "voxtral-mini-tts-2603"
    voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8"  # Paul - Neutral (default)
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

Telegram 语音气泡与 ffmpeg

Telegram 的语音气泡要求使用 Opus/OGG 格式的音频：

• OpenAI、ElevenLabs 和 Mistral 原生输出 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 的音频将以普通音频文件形式发送（可播放，但显示为矩形播放器而非语音气泡）。

tip

如希望不安装 ffmpeg 即实现语音气泡，建议切换至 OpenAI、ElevenLabs 或 Mistral 提供商。

语音消息转录（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 则优先使用。模型大小如下：

模型	大小	速度	音质
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 未设置 → 自动检测中跳过，继续尝试下一个可用服务
• 所有服务均不可用 → 语音消息将原样传递，并向用户附上准确提示