技能介绍

在内容生产流程里，把一段纯文本变成可播放、可下载的语音文件，看似只是“调用一个 TTS 接口”，但实际落地时经常会遇到几个具体问题：语音库里哪些音色真正兼容 TTS、哪些只是视频旁白音色；拿到一段长文本后，语速、停顿、多语言口音如何一次调到位；以及怎样在不做视频合成的前提下，只产出音频用于播客、有声笔记或字幕配音。这个技能专门解决这几件事。

解决什么问题

它面向的是独立音频生成场景：输入一段 1-5000 字符的文本，输出一个可直接下载或播放的语音文件。与 HeyGen 视频生成流程解耦，不涉及画面渲染，只专注把文字变成语音这一环节。

如何工作

核心能力分两步走：

查询可用音色：调用 GET /v3/voices?engine=starfish，通过 engine=starfish 过滤出真正支持 TTS 的音色。这一点很关键——v3 的 /v3/voices 是统一音色入口，视频旁白音色和 TTS 音色混在一起，不加过滤很容易选到一个无法生成语音的音色。
生成语音音频：调用 POST /v3/voices/speech，传入 text 和 voice_id，返回 audio_url。支持调整 speed（0.5-2.0）、指定 language 和 locale（如 en-US、pt-BR），也可以把 input_type 设为 ssml 来使用完整的 SSML 标记。

标准工作流是：先列出音色 → 按语言、性别、特征挑选 → 调用生成接口 → 用返回的 audio_url 下载或播放。如果环境里已经装好 HeyGen 的 MCP 工具，优先走 mcp__heygen__* 系列工具，而不是自己拼 HTTP 请求。

几个值得注意的点

音色列表是分页的，需要根据 next_token 翻页拉全，否则容易漏掉可用音色。
locale 只对多语言音色生效，调用前先确认该音色支持 support_locale。
自然语速建议落在 0.8-1.2 之间，过快或过慢都会影响听感。
停顿控制：可以直接在文本里加 <break time="1s" /> 这类标签，前后留空格；需要更精细的 SSML 控制时，把 input_type 设为 ssml。
响应里带有 word_timestamps，可以用来做字幕同步或时间轴对齐。
鉴权：所有请求都需要在请求头里带上 X-Api-Key，通过环境变量 HEYGEN_API_KEY 注入。