Foreword¶

Video and podcast creators frequently encounter this need: the script is ready, but the voiceover is missing. They don’t want to hire a voice actor, nor do they want to compare prices and configure APIs across multiple TTS services. This Skill wraps HeyGen’s Starfish TTS model into a standard skill, providing two actions: listing voices and synthesizing speech. You can call it directly within your scripts.

It does one thing only: generating standalone audio files from text. It does not handle video generation; for that, you need to use HeyGen’s video API separately.

What is this¶

Text to Speech is an Agent Skill based on the general SKILL.md format, published and maintained by michaelwang11394 (Michael Wang). The source repository is ClawHub, with coordinates @clawhub_michaelwang11394/text-to-speech-heygen, version 2.23.0, categorized under design-media.

It solves the problem of: when an Agent needs voice output in a conversation or task flow, it doesn’t have to manually construct HTTP requests or handle pagination and voice filtering; it can simply follow the process defined by the skill.

Official Links:

• SkillHub Mirror: https://api.skillhub.cn/zcwl/text-to-speech-heygen
• Upstream Repository: https://clawhub.ai/michaelwang11394/text-to-speech-heygen

Core Features¶

According to the official SKILL.md, this Skill offers two capabilities.

1. List available voices. It calls HeyGen’s unified voice API with the engine=starfish filter to return only voices that support Starfish TTS. Note that not all video voices support Starfish TTS. The results are paginated and require the use of next_token for paging.

2. Synthesize speech. It submits text and a specified voice_id to the synthesis API, retrieves the audio_url, and then downloads or plays it.

The accompanying data fields are also provided in the SKILL.md: voice items include voice_id, name, language, gender, preview_audio_url, support_pause, support_locale, type; synthesis results include audio_url, duration, request_id, and optionally return word_timestamps.

Installation and Activation¶

The installation command provided by the upstream ClawHub is openclaw skills install. The SkillHub mirror page offers the same coordinates.

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

After installation, authentication must be configured. All requests must include the X-Api-Key header, provided via an environment variable:

export HEYGEN_API_KEY="Your HeyGen API Key"

The Skill metadata marks requires_api_key=true, indicating that the API cannot be called without this Key.

Regarding differences with Cursor, Codex CLI, and Claude Code: Official documentation only specifies the ClawHub/openclaw installation method and does not provide integration instructions for these specific tools. No unverified content will be supplemented here. If you need to enable it in these tools, it is recommended to first confirm whether the corresponding skill loading mechanism supports ClawHub coordinates.

Typical Usage¶

Let’s walk through the default flow according to the official SKILL.md: first, query voices, then select a voice, and finally synthesize.

Step 1: List voices supported by Starfish:

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

Supported query parameters include engine, type (public or private), language, gender, limit (1-100 items per page), and token (pagination cursor, take the next_token from the previous page).

Step 2: Synthesize speech. text is required, with a length of 1-5000 characters; voice_id is required, taken from the results of step one.

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
  }'

Other optional fields:

Return example:

{
  "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 }
    ]
  }
}

If HeyGen MCP tools are already available in the runtime environment, the SKILL.md suggests prioritizing tools over direct HTTP requests. The mapping is: use mcp__heygen__list_audio_voices for listing voices and mcp__heygen__text_to_speech for synthesis.

The official documentation also provides examples for several common combinations: basic synthesis, adjusting speech rate (speed: 1.1), multilingual voices (language: "pt" with locale: "pt-BR"), and SSML input. The first three categories are just field differences; in curl, this means adding keys to the -d payload.

Use Cases and Notes¶

Suitable scenarios: adding narration to video scripts, generating raw audio for podcasts or commentary, batch converting copy into audio archives, and scenarios requiring voice filtering by language and gender.

Things to note:

1. The text length limit is 5000 characters. Long scripts must be segmented manually and concatenated after multiple calls.

2. Voice filtering must include engine=starfish. Video voices obtained via the standard /v3/voices may not be available for TTS.

3. The voice list is paginated. Taking only the first page will result in missing voices; limit is max 100, and you need to loop through next_token.

4. Multilingual voices require both language and locale; providing only language may fail to select the expected pronunciation.

5. Speech synthesis and video generation are two separate APIs; this Skill only covers the former.

6. A valid HeyGen API Key is required; quotas and billing are subject to the HeyGen account.

Conclusion¶

The value of this Skill lies in wrapping HeyGen Starfish TTS’s two APIs, along with details like pagination and voice filtering, into a reusable flow, saving the effort of handwriting requests every time. Its scope is clear: it only converts text to speech files.

Official Link: https://api.skillhub.cn/zcwl/text-to-speech-heygen