ElevenLabs TTS 轉 MP3
透過 ElevenLabs 文字轉語音 API 將腳本文字轉換為 MP3 配音。
預設值
- 語音 ID：
K7ewtjKRNtwwt3lKQ6M0（Hoang 的品牌聲音 — 已鎖定）— 可透過ELEVENLABS_VOICE_ID環境變數或--voice_id覆蓋 - 模型：
eleven_v3（最具表現力，支援音訊標籤如 [excited]、[whisper]、[laugh]；最適合敘事內容）— 可透過--model_id覆蓋。替代方案：eleven_multilingual_v2（高品質，較慢）、eleven_turbo_v2_5（快速，稍微平淡）、eleven_flash_v2_5（最快） - 輸出格式：
mp3_44100_128（44.1 kHz / 128 kbps）— 可透過--output_format覆蓋 - 語音設定：
stability=0.5、similarity_boost=0.75、style=0、use_speaker_boost=true（ElevenLabs 預設值） - 發音地圖：自動從
assets/vn-pronunciation-map.json載入 — 使用--no-pronounce-map停用，或使用--pronounce-map path.json指向不同檔案 - 字元限制：每次請求 5000 字元（ElevenLabs 硬性限制）。文字超過 5000 字元 → 腳本會退出並顯示錯誤，要求使用者手動分割。
快速使用
從檔案
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
--file path/to/script.txt \
-o workspace/content/YYYY-MM-DD/voiceover.mp3
從內嵌文字
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
"Xin chào các bạn, hôm nay mình chia sẻ về AI Agent" \
-o workspace/assets/elevenlabs/sample.mp3
自訂語音 / 模型
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
--file script.txt \
--voice_id K7ewtjKRNtwwt3lKQ6M0 \
--model_id eleven_turbo_v2_5 \
-o output.mp3
調整語音表現力
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
--file script.txt \
--stability 0.4 \
--similarity_boost 0.8 \
--style 0.2 \
-o output.mp3
語音設定 — 何時調整
| 設定 | 範圍 | 效果 |
|---|---|---|
stability | 0.0–1.0 | 越高越單調/可預測；越低越情緒化/多變。0.5 是旁白的最佳點。輕鬆的鉤子可降至 0.3–0.4；正式的解釋影片可升至 0.7 以上。 |
similarity_boost | 0.0–1.0 | 克隆參考語音的緊密程度。預設 0.75。如果語音聽起來與原版「有偏差」，可提高至 0.9。 |
style | 0.0–1.0 | 風格誇張程度。預設 0。大於 0 時會增加延遲。對於表現力內容（0.1–0.3）很有用。 |
use_speaker_boost | bool | 提高說話者相似度。為保持品牌語音一致性，請保持 true。 |
發音地圖（英文單詞修正）
ElevenLabs 多語言模型會嘗試以主要語言朗讀整個文字。在越南文腳本中，英文單詞如 doc、chat、git 會被當作越南音節發音，聽起來很奇怪。為了解決這個問題，無需手動編輯每個腳本，此技能會從 assets/vn-pronunciation-map.json 自動載入一個整詞大小寫不敏感的替換地圖，並在將文字發送到 API 之前應用它。
預設對應：
{
"doc": "đóc",
"chat": "chát",
"git": "gít"
}
運作方式：每個鍵值會以 \b...\b 邊界進行大小寫不敏感比對，然後以越南語拼音替換。模型會看到「đóc」而不是「doc」，並將其發音接近 /dɒk/。這只影響音訊 — 您的原始腳本保持不變。
管理字典 — 先聆聽，再新增：
- 在包含候選詞的簡短測試腳本上執行此技能
- 如果模型已經正確讀取，請不要新增它（過度擬合會破壞事情）
- 注意衝突：新增
"code"也會改寫Claude Code（品牌名稱）中的Code→ 永遠不要這樣做 - 對於需要保護的品牌名稱，完全將它們排除在外
覆蓋 / 停用：
# 為特定專案使用自訂地圖
uv run scripts/text_to_mp3.py --file s.txt --pronounce-map workspace/.../map.json -o out.mp3
# 完全跳過替換
uv run scripts/text_to_mp3.py --file s.txt --no-pronounce-map -o out.mp3
腳本會將每個套用的替換輸出到 stderr（例如 'doc' -> 'đóc' (4x)），以便您驗證更改內容。
工作流程
- 從專案
.env載入ELEVENLABS_API_KEY - 從
--file或位置引數讀取文字，去除空白 - 應用發音地圖（除非使用
--no-pronounce-map）— 整詞大小寫不敏感替換 - 驗證
len(text) <= 5000 POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}?output_format=mp3_44100_128- 標頭：
xi-api-key: <key>、Content-Type: application/json、Accept: audio/mpeg - 主體：
{ "text": "...", "model_id": "eleven_v3", "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "style": 0, "use_speaker_boost": true } }
- 標頭：
- 將音訊位元組直接串流到輸出 MP3（無需轉碼 — 伺服器直接回傳 MP3）
- 輸出
output_path、size_mb、char_count、voice_id、model_id
輸出慣例
- 短音訊/測試：
workspace/assets/elevenlabs/<name>.mp3 - 影片製作：
workspace/content/YYYY-MM-DD/video-short/<project>/voiceover.mp3
需求
- 專案
.env中的ELEVENLABS_API_KEY（標頭認證：xi-api-key） - 可選的
.env中的ELEVENLABS_VOICE_ID，用於鎖定不同的預設語音 - Python 依賴項透過 PEP 723 內嵌元資料管理（由
uv run自動安裝）：requests、python-dotenv - 不需要
ffmpeg— ElevenLabs 直接回傳 MP3
為什麼不分塊
ElevenLabs 將請求限制在 5000 字元。此技能在超過該限制時快速失敗，而不是自動分割，原因如下：
- 單個配音應該是一個連貫的區塊 — 在腳本中間分割會導致串接邊界的韻律跳躍
- 使用者的內容（鉤子、簡短腳本、影片片段）通常遠低於 5000 字元
- 如果使用者確實需要更長的音訊，他們應該以語義方式分割腳本（段落分隔），並為每個區塊呼叫此技能，然後在自己的管道中使用 ffmpeg 串接
API 參考資料
- 端點：
POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id} - 認證：
xi-api-key: <api_key>標頭 - 型號目錄：https://elevenlabs.io/docs/models
- 語音目錄（瀏覽/取得語音 ID）：https://elevenlabs.io/app/voice-library
- API 文件：https://elevenlabs.io/docs/api-reference/text-to-speech/convert
- 速率限制：取決於方案層級 — 請參閱 https://elevenlabs.io/pricing
- 輸出格式：
mp3_44100_128（預設）、mp3_44100_192（更高品質，僅付費方案）、pcm_44100、ulaw_8000（電話用途）