语音与 TTS

Hermes Agent 同时支持文本转语音输出，以及在所有消息平台上的语音消息转写。

Nous 订阅用户

如果你拥有付费 Nous Portal 订阅，就可以通过 Tool Gateway 使用 OpenAI TTS，而无需额外的 OpenAI API key。运行 hermes model 或 hermes tools 即可启用。

文本转语音

可通过九种大模型提供商（provider）进行文本转语音：

提供方	质量	成本	API Key
Edge TTS（默认）	良好	免费	无需
ElevenLabs	极佳	付费	`ELEVENLABS_API_KEY`
OpenAI TTS	良好	付费	`VOICE_TOOLS_OPENAI_KEY`
MiniMax TTS	极佳	付费	`MINIMAX_API_KEY`
Mistral (Voxtral TTS)	极佳	付费	`MISTRAL_API_KEY`
Google Gemini TTS	极佳	有免费额度	`GEMINI_API_KEY`
xAI TTS	极佳	付费	`XAI_API_KEY`
NeuTTS	良好	免费（本地）	无需
KittenTTS	良好	免费（本地）	无需

平台投递方式

平台	投递形式	格式
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" | "gemini" | "xai" | "neutts" | "kittentts"
  speed: 1.0                    # Global speed multiplier (provider-specific settings override this)
  edge:
    voice: "en-US-AriaNeural"   # 322 voices, 74 languages
    speed: 1.0                  # Converted to rate percentage (+/-%)
  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
    speed: 1.0                  # 0.25 - 4.0
  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)
  gemini:
    model: "gemini-2.5-flash-preview-tts"  # or gemini-2.5-pro-preview-tts
    voice: "Kore"               # 30 prebuilt voices: Zephyr, Puck, Kore, Enceladus, Gacrux, etc.
  xai:
    voice_id: "eve"             # xAI TTS voice (see https://docs.x.ai/docs/api-reference#tts)
    language: "en"              # ISO 639-1 code
    sample_rate: 24000          # 22050 / 24000 (default) / 44100 / 48000
    bit_rate: 128000            # MP3 bitrate; only applies when codec=mp3
    # base_url: "https://api.x.ai/v1"   # Override via XAI_BASE_URL env var
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu
  kittentts:
    model: KittenML/kitten-tts-nano-0.8-int8   # 25MB int8; also: kitten-tts-micro-0.8 (41MB), kitten-tts-mini-0.8 (80MB)
    voice: Jasper                               # Jasper, Bella, Luna, Bruno, Rosie, Hugo, Kiki, Leo
    speed: 1.0                                  # 0.5 - 2.0
    clean_text: true                            # Expand numbers, currencies, units

语速控制：全局 tts.speed 默认会作用于所有提供方；每个提供方也可用自己的 speed 配置覆盖它，例如 tts.openai.speed: 1.5。提供方专属配置优先级更高。默认值为 1.0（正常速度）。

Telegram 语音气泡与 ffmpeg

Telegram 语音气泡要求音频为 Opus/OGG 格式：

OpenAI、ElevenLabs 和 Mistral 原生输出 Opus，无需额外设置
Edge TTS（默认）输出 MP3，需要 ffmpeg 转换
MiniMax TTS 输出 MP3，也需要 ffmpeg 才能用于 Telegram 语音气泡
Google Gemini TTS 输出原始 PCM，借助 ffmpeg 直接编码为 Opus
xAI TTS 输出 MP3，需要 ffmpeg 转换
NeuTTS 输出 WAV，也需要 ffmpeg 转换
KittenTTS 输出 WAV，也需要 ffmpeg 转换

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Fedora
sudo dnf install ffmpeg

如果没有 ffmpeg，Edge TTS、MiniMax TTS、NeuTTS 和 KittenTTS 仍可发送为普通音频文件（可播放，但显示为矩形音频播放器，而不是语音气泡）。

提示

如果你希望直接获得语音气泡效果而不安装 ffmpeg，可以切换到 OpenAI、ElevenLabs 或 Mistral 提供方。

语音消息转写（STT）

在 Telegram、Discord、WhatsApp、Slack 或 Signal 中发送的语音消息，会被自动转写为文本并注入会话。对智能体来说，这些转写结果就像普通文本一样。

提供方	质量	成本	API Key
本地 Whisper（默认）	良好	免费	无需
Groq Whisper API	良好到极佳	有免费额度	`GROQ_API_KEY`
OpenAI Whisper API	良好到极佳	付费	`VOICE_TOOLS_OPENAI_KEY` 或 `OPENAI_API_KEY`

零配置

如果已安装 faster-whisper，本地转写即可开箱即用。如果不可用，Hermes 也会尝试调用本地 whisper CLI（包括常见安装路径如 /opt/homebrew/bin），或通过 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

提供方细节

Local (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 key → 回退到本地转写，再回退到 OpenAI
未设置 OpenAI key → 回退到本地转写，再回退到 Groq
Mistral key / SDK 未设置 → 在自动检测中跳过，继续尝试下一个可用提供方
什么都不可用 → 语音消息会原样透传，并向用户明确说明当前无法转写

文本转语音​

平台投递方式​

配置​

Telegram 语音气泡与 ffmpeg​

语音消息转写（STT）​

配置​

提供方细节​

回退行为​