SuperAPI AI Directory

elevenlabs-tts

General & other

View repository

Updated 10-16 08:36

About this skill

Skill: elevenlabs-tts

Exclusive skill (only for companion/Mira) Version: 1.0.0


Feature Description

Call the ElevenLabs TTS API to synthesize text into speech, directly outputting ogg_opus format (no ffmpeg transcoding needed), sent via Telegram sendVoice interface. Supports natural switching between Chinese and English, and supportsvoice cloning—upload audio samples to configure a custom voice in the Lin Chi-ling style.


API Specifications

Parameter Value
Endpoint https://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream
Model eleven_multilingual_v2(best for mixed Chinese-English) / eleven_flash_v2_5(low latency)
Default voice Built-in female voice (see recommended list below)
Output format ogg_opus(natively supported, Telegram sendVoice can be used directly,no ffmpeg needed)
Maximum text length 5,000 characters
Authentication method xi-api-key: {ELEVENLABS_API_KEY}

Recommended Voice Options

Built-in voices (available with zero configuration)

Voice name Style Chinese performance Use case
Sarah Gentle, warm Good Mira emotional companionship (recommended starting point)
Rachel Steady, intellectual Good evening / weekly quiet messages
Aria Clear, neutral Good Daily conversation

Built-in voices are all native English speakers; when handling Chinese via eleven_multilingual_v2 there is a slight foreign accent, suitable for use when users accept this style.

Voice cloning (recommended for natural pure Chinese pronunciation)

Clone a voice via ElevenLabs Voice Lab to achieve natural Chinese pronunciation close to the Lin Chi-ling style:

1. 登录 ElevenLabs → Voice Lab → Add Voice → Instant Voice Cloning
2. 上传 1-5 分钟高质量中文音频(清晰、少背景噪声、情感自然)
3. 命名声音(如 "Mira_ZH"),完成克隆后获取 Voice ID
4. 将 Voice ID 填入 ~/.openclaw/.env.local 的 ELEVENLABS_VOICE_ID 字段

The quality of the cloned voice depends on the sample audio quality: clear, emotionally rich, and over 1 minute works best.


Calling the Interface

speak(text, voice_id=None, output_path=None) → str

输入:
  text        必填,要合成的文字
  voice_id    可选,覆盖 ELEVENLABS_VOICE_ID 环境变量配置
  output_path 可选,指定输出路径(默认 /tmp/mira_tts_{uuid}.ogg)

输出:
  str — 生成的 ogg 文件绝对路径

异常:
  ElevenLabsTTSError — API 调用失败(含 HTTP 状态码)
  QuotaExceededError — 月度字符额度耗尽(HTTP 429)

Synthesis Workflow

1. 读取 ELEVENLABS_VOICE_ID(未配置则使用内置 Sarah voice ID)
2. POST /v1/text-to-speech/{voice_id}/stream:
   Headers:
     xi-api-key: {ELEVENLABS_API_KEY}
     Accept: audio/ogg; codecs=opus
     Content-Type: application/json
   Body:
   {
     "text": "<消息文字>",
     "model_id": "eleven_multilingual_v2",
     "voice_settings": {
       "stability": 0.65,
       "similarity_boost": 0.80,
       "style": 0.35,
       "use_speaker_boost": true
     }
   }
3. 流式接收 ogg_opus 数据,写入 /tmp/mira_tts_{uuid}.ogg
4. 返回 .ogg 文件路径

Parameter Description:stability: 0.65 — retains emotional flexibility, not too mechanical;style: 0.35 — slightly stylized, natural without being exaggerated. Can be fine-tuned in the voice_style field of USER.md.


Integration with Telegram

After generating the .ogg file, send via sendVoice :

POST https://api.telegram.org/bot{TG_BOT_TOKEN_COMPANION}/sendVoice
Content-Type: multipart/form-data

chat_id: <TG_ADMIN_CHAT_ID>
voice:   <.ogg 文件>
caption: <原始文字>(可选,作为字幕)

Delete the temporary .ogg file immediately after sending.


Usage Tracking

ElevenLabs bills by character; record usage after each call:

// ~/.openclaw/workspaces/companion/logs/elevenlabs-usage.json
{
  "month": "2026-02",
  "totalChars": 12450,
  "limitChars": 30000,
  "remaining": 17550,
  "lastUpdated": "2026-02-25T10:30:00Z"
}

When the remaining quota falls below 10%, automatically downgrade to text sending and notify the user via Telegram to check usage.


Text Preprocessing Rules

Item Rule
Markdown symbols Remove **、_、~、` and other formatting symbols
URL Replace with "a link"
Emoji Keep (multilingual v2 will handle naturally)
Oversized messages When > 500 characters, truncate to the first 500 characters; also send the full text version

Voice Sending Timing

Same as minimax-tts, the trigger logic is controlled by the proactive-chat skill:

Trigger type Default behavior Reason
morning Voice-first Morning greetings are good for listening
evening Voice-first Stronger sense of companionship at night
weekly Voice-first Emotional reviews are good for conveying through voice
discovery Text-first Content containing links/quotes is not suitable for reading aloud
Direct user dialogue Text (unless the user requests otherwise) Dialogue reply efficiency takes priority

Users can, in USER.md 's voice_messages field, disable voice (enabled: false) or adjust voice_style(stability/similarity parameters).


Fallback strategy

Condition Handling
ELEVENLABS_API_KEY is not configured Fall back to text, record a warn log
HTTP 4xx / 5xx Fall back, record an error log
Monthly quota exhausted (HTTP 429) Fall back, notify the user to top up
Remaining balance < 10% Automatically fall back, notify the user
Text < 5 characters Fall back
USER.md voice_messages.enabled: false Fall back
Discovery message contains an external link Fall back

Environment variable

Variable Required Description
ELEVENLABS_API_KEY ✅ ElevenLabs platform API Key (elevenlabs.io)
ELEVENLABS_VOICE_ID Optional Custom/cloned voice ID (if not configured, the built-in Sarah is used)

Dependencies

  • requests(Python HTTP request)
  • No ffmpeg needed (native ogg_opus output)
  • ELEVENLABS_API_KEY
  • TG_BOT_TOKEN_COMPANION、TG_ADMIN_CHAT_ID

Logs

  • Synthesis successful:~/.openclaw/workspaces/companion/logs/tts.log(records voice_id, character count, elapsed time)
  • Usage tracking:~/.openclaw/workspaces/companion/logs/elevenlabs-usage.json
  • Fallback records:tts.log(including the fallback reason)
  • Errors:~/.openclaw/workspaces/companion/logs/error.log

Comparison with minimax-tts

Dimension elevenlabs-tts minimax-tts
Chinese naturalness ⭐⭐⭐⭐ Good (multilingual v2) ⭐⭐⭐⭐⭐ Excellent (native Chinese)
Mixed Chinese and English ⭐⭐⭐⭐⭐ Excellent ⭐⭐⭐⭐ Good
ogg output ✅ Natively supported, no ffmpeg needed ❌ Requires ffmpeg transcoding
Voice cloning ✅ Supported (Instant Cloning) ❌ Not supported
Latency ~600–1200ms ~300–600ms
Cost Medium (Starter $5/30K characters) Low (more cost-effective for Chinese scenarios)
Recommended scenarios Voice cloning, mixed Chinese and English messages Pure Chinese, low latency, low cost