Text to Speech

核心用法

Text-to-Speech (HeyGen Starfish) 是HeyGen自研的语音合成技能，专注于独立音频生成（非视频场景）。用户通过调用 /v1/audio 端点，将文本转换为自然流畅的语音输出。

主要功能

1. 语音列表获取：调用 mcp__heygen__list_audio_voices 或直接请求 GET /v1/audio/voices，获取支持Starfish TTS的完整音色库（含语言、性别、预览音频等元数据）
2. 语音合成：通过 mcp__heygen__text_to_speech 或 POST /v1/audio/text_to_speech 提交文本，支持以下参数：

3. SSML断句：支持 <break time="1.5s"/> 标签控制停顿节奏

• 基础调节：语速（0.5-1.5倍）、音高（-50至50）
• 多语言支持：locale 参数指定口音（如 en-US、pt-BR）
• ElevenLabs高级设置：模型选择、相似度、稳定性、风格强度

响应特性

• 返回可直接播放的 audio_url、音频时长 duration
• 提供逐词时间戳 word_timestamps，便于字幕同步

显著优点

| 优势 | 说明 |

|------|------|

| **自研模型** | HeyGen Starfish为in-house TTS，非第三方依赖，可控性高 |

| **参数精细** | 语速/音高/口音多维调节，支持专业级音频定制 |

| **时间戳对齐** | 自动输出词级时间戳，降低后期剪辑成本 |

| **MCP工具链** | 提供标准化MCP工具封装，开发集成效率高 |

| **多语言覆盖** | 支持英语、中文、葡萄牙语等多种语言及本地化口音 |

潜在缺点与局限性

1. 音色库边界：GET /v1/audio/voices 与 GET /v2/voices 为不同端点，部分视频可用音色不支持Starfish TTS，需显式筛选
2. 预览音频缺失：部分音色 preview_audio_url 为null，无法提前试听
3. ElevenLabs配置门槛：高级参数需理解TTS模型特性，普通用户上手成本较高
4. 断句标签限制：SSML break标签语法严格（需空格包围、秒级单位），格式错误将直接导致失败
5. API依赖风险：服务稳定性绑定HeyGen基础设施，无离线/本地部署选项

适合人群

• 内容创作者：播客主播、有声书制作人、教育课程开发者
• 产品团队：需要批量生成产品演示配音、IVR语音导航
• 开发者：通过MCP工具快速集成TTS能力至自动化工作流
• 多语言运营：跨境电商、国际化SaaS需本地化语音内容

常规风险

| 风险类型 | 具体表现 | 缓释建议 |

|----------|----------|----------|

| **成本累积** | 高频调用导致API费用上升 | 设置预算告警，缓存常用音频 |

| **内容合规** | 合成语音可能被滥用于虚假信息 | 建立内容审核机制，保留生成日志 |

| **授权隐患** | 商用场景需确认HeyGen授权条款 | 审阅服务条款，必要时购买企业许可 |

| **音频质量波动** | 极端参数（如speed<0.8或>1.2）导致语音 unnatural | 遵循最佳实践建议范围 |

| **密钥泄露** | `HEYGEN_API_KEY` 硬编码或泄露 | 使用环境变量+密钥管理服务，定期轮换 |

认证与工具建议

• 必须配置：HEYGEN_API_KEY 环境变量
• 优先路径：存在 mcp__heygen__* 工具时，优先使用MCP而非直接HTTP调用
• 调试技巧：利用返回的 request_id 追踪异常请求

核心用法

本 Skill 为纯文档型 API 参考指南，用于调用 HeyGen Starfish TTS 模型生成高质量语音音频。核心工作流程包含三步：首先通过 mcp__heygen__list_audio_voices 或 GET /v1/audio/voices 获取可用语音列表，筛选匹配目标语言、性别及功能特性的语音；随后调用 mcp__heygen__text_to_speech 或 POST /v1/audio/text_to_speech 提交文本与 voice_id 进行合成；最终获取返回的 audio_url 下载或播放音频。支持通过 speed（0.5-1.5）、pitch（-50 至 50）、locale 等参数精细调控输出效果，并可使用 SSML 风格的 <break time="1s"/> 标签插入停顿控制节奏。

显著优点

权威技术底座：依托 HeyGen 自研 Starfish TTS 模型，该模型专为高质量语音合成设计，非简单调用第三方服务，语音自然度与表现力优于通用 TTS 方案。精细化控制能力：提供速度、音高、地域口音（locale）多维调节，支持 ElevenLabs 高级参数（similarity_boost、stability、style），满足专业级音频制作需求。工程友好设计：完整提供 curl、TypeScript、Python 三种语言的请求示例与类型定义，响应包含 word_timestamps 字段便于字幕同步或时间轴对齐，大幅降低集成成本。安全合规保障：纯文档无执行代码，无敏感信息硬编码风险，外部 API 均为 HeyGen 官方 TLS 1.3 加密服务，通过 GDPR/CCPA 合规审查。

潜在缺点与局限性

生态绑定成本：深度依赖 HeyGen 专有 API，需单独申请 HEYGEN_API_KEY，无法与其他 TTS 服务（如 Azure Speech、Google Cloud TTS）无缝切换。语音库边界：GET /v1/audio/voices 与视频制作用的 GET /v2/voices 为不同端点，部分视频语音不支持 Starfish TTS，可用语音数量存在上限。功能单一性：专注独立音频生成，与视频生成、数字人合成等 HeyGen 核心能力解耦，如需完整音视频方案需额外集成其他 Skill。网络与计费依赖：音频生成完全云端化，无离线能力；按调用量计费模式下长文本合成成本需提前评估。预览可用性：部分语音的 preview_audio_url 可能为 null，实际效果需生成后验证。

适合的目标群体

内容创作者与播客制作人：需快速生成多语言旁白、节目开场白、广告口播等音频素材。视频编辑与后期团队：为宣传片、教程、产品演示视频批量配音，利用 word_timestamps 精准对齐字幕。开发者与自动化工程师：构建有声读物生成、智能客服语音回复、语音通知等自动化工作流。营销与运营人员：制作多语言版本营销音频，通过 speed/pitch 微调匹配品牌调性。教育科技团队：生成课程讲解音频、语言学习跟读材料，利用 locale 参数实现口音教学。

常规使用风险

性能与稳定性：HeyGen API 存在速率限制与偶发延迟，批量生成任务需设计重试与队列机制；音频 URL 为临时资源，需及时下载持久化存储。成本控制：未内置用量统计与预算预警，长文本或多语言变体生成可能导致费用超支，建议集成前测试字符单价。密钥管理风险：HEYGEN_API_KEY 泄露将导致账户被盗用，需严格遵循环境变量注入原则，禁用版本控制提交。内容合规风险：TTS 内容需符合 HeyGen 服务条款，禁止生成欺诈、侵权、虚假信息音频；多语言 locale 设置错误可能导致文化敏感内容输出不当。数据残留顾虑：虽然 Skill 本身不存储数据，但文本内容经 HeyGen 服务端处理，涉及敏感信息的场景建议查阅其隐私政策并评估合规义务。