前言¶

做视频或播客的人经常遇到这类需求：脚本已经写好了，就差一段配音，不想找人录，也不想在多个 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