前言¶

做視頻或播客的人經常遇到這類需求：腳本已經寫好了，就差一段配音，不想找人錄，也不想在多個 TTS 服務之間比價調接口。這個 Skill 把 HeyGen 的 Starfish TTS 模型封裝成標準 skill，給出音色列表和合成兩個動作，腳本里直接調用即可。

它只做一件事：把文本生成獨立語音音頻文件。它不做視頻生成，那部分要另找 HeyGen 的視頻接口。

這是什麼¶

Text to Speech 是一個基於通用 SKILL.md 格式的 Agent Skill，由 michaelwang11394（Michael Wang）發佈並維護，來源倉庫爲 ClawHub，座標 @clawhub_michaelwang11394/text-to-speech-heygen，版本 2.23.0，分類 design-media。

它解決的是：Agent 在對話或任務流中需要語音產出時，不必自己拼 HTTP 請求、不必處理分頁和音色篩選，直接按 skill 約定的流程走即可。

官方地址：

• SkillHub 鏡像：https://api.skillhub.cn/zcwl/text-to-speech-heygen
• 上游倉庫：https://clawhub.ai/michaelwang11394/text-to-speech-heygen

核心功能¶

根據官方 SKILL.md，這個 Skill 提供兩條能力。

1、列出可用音色。調用 HeyGen 的統一音色接口，用 engine=starfish 過濾，只返回支持 Starfish TTS 的音色。注意不是所有視頻音色都支持 Starfish TTS。返回結果分頁，需要用 next_token 翻頁。

2、合成語音。把文本和指定 voice_id 提交到合成接口，拿到 audio_url，再下載或播放。

配套的數據字段也在 SKILL.md 中給出：音色項包含 voice_id、name、language、gender、preview_audio_url、support_pause、support_locale、type；合成結果包含 audio_url、duration、request_id，並可選返回 word_timestamps。

安裝與啓用¶

上游 ClawHub 給出的安裝命令是 openclaw skills install。SkillHub 鏡像頁也提供了同樣的座標。

openclaw skills install @michaelwang11394/text-to-speech-heygen

裝完後需要配置鑑權。所有請求都要帶 X-Api-Key 頭，通過環境變量提供：

export HEYGEN_API_KEY="你的HeyGen API Key"

Skill 元數據裏標記了 requires_api_key=true，說明沒有這個 Key 就無法調用。

關於 Cursor、Codex CLI、Claude Code 的差異：官方資料只寫了 ClawHub/openclaw 的安裝方式，沒有給出這幾種工具各自的接入說明，這裏不補充未覈實的內容。如果需要在這些工具裏啓用，建議先確認對應的 skill 加載機制是否支持 ClawHub 座標。

典型用法¶

下面按官方 SKILL.md 的默認流程走一遍：先查音色，再挑音色，最後合成。

第一步，列出 Starfish 支持的音色：

curl -X GET "https://api.heygen.com/v3/voices?engine=starfish" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

支持的查詢參數有 engine、type（public 或 private）、language、gender、limit（每頁 1-100 條）、token（分頁游標，取上一頁的 next_token）。

第二步，合成語音。text 必填，長度 1-5000 字符；voice_id 必填，取自第一步的結果。

curl -X POST "https://api.heygen.com/v3/voices/speech" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello! Welcome to our product demo.",
    "voice_id": "YOUR_VOICE_ID",
    "speed": 1.0
  }'

其餘可選字段：

返回示例：

{
  "error": null,
  "data": {
    "audio_url": "https://resource2.heygen.ai/text_to_speech/.../id=365d46bb.wav",
    "duration": 5.526,
    "request_id": "p38QJ52hfgNlsYKZZmd9",
    "word_timestamps": [
      { "word": "Hey", "start": 0.079, "end": 0.219 }
    ]
  }
}

如果運行環境裏已經有 HeyGen 的 MCP 工具，SKILL.md 建議優先用工具而不是直接發 HTTP 請求。對應關係是：列音色用 mcp__heygen__list_audio_voices，合成用 mcp__heygen__text_to_speech。

官方還給了幾個常見組合的寫法，分別是基礎合成、調語速（speed: 1.1）、多語言音色（language: "pt" 加 locale: "pt-BR"）、以及 SSML 輸入。前三類都只是字段差異，換成 curl 就是往 -d 里加鍵。

適用場景與注意¶

適合的場景：需要給視頻腳本配旁白、給播客或解說做幹聲、批量把文案轉成音頻存檔，以及需要按語言和性別篩音色的情況。

需要注意的地方：

1、文本長度上限 5000 字符。長文案要自己分段，多次調用後拼接。

2、音色篩選必須帶 engine=starfish。用普通 /v3/voices 拿到的視頻音色，不一定能用於 TTS。

3、音色列表分頁。只取第一頁會漏掉音色，limit 最大 100，需要循環 next_token。

4、多語言音色要同時給 language 和 locale，只給 language 可能選不到預期發音。

5、語音合成與視頻生成是兩個接口，這個 Skill 只覆蓋前者。

6、需要有效的 HeyGen API Key，配額和計費以 HeyGen 賬號爲準。

結尾¶

這個 Skill 的價值在於把 HeyGen Starfish TTS 的兩個接口和分頁、音色篩選這些細節封裝成可複用流程，省掉每次手寫請求的工夫。它範圍明確，只做文本轉語音文件。

官方地址：https://api.skillhub.cn/zcwl/text-to-speech-heygen