Text to Speech

If you want to generate audio from text without creating a video, HeyGen offers a dedicated TTS engine called Starfish. Pass a script and a compatible voice ID — get back an audio file URL.

Starfish only works with Starfish-compatible voices. Not all HeyGen voices support this engine. Use GET /v3/voices?engine=starfish to get a list of compatible voices before calling this endpoint.

Quick Example

curl

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 from HeyGen!",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2"
  }'

Response

{
  "data": {
    "audio_url": "https://files.heygen.ai/audio/req_xyz789.mp3",
    "duration": 2.4,
    "request_id": "req_xyz789",
    "word_timestamps": [
      { "word": "Hello", "start": 0.0, "end": 0.45 },
      { "word": "from", "start": 0.45, "end": 0.72 },
      { "word": "HeyGen!", "start": 0.72, "end": 1.35 }
    ]
  }
}

Finding a Compatible Voice

Before calling this endpoint, find a Starfish-compatible voice_id:

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

See Browse Voices for full filtering and pagination details.

Parameters

Parameter	Type	Required	Default	Description
text	string	Yes	—	Text to synthesize (1–5,000 characters).
voice_id	string	Yes	—	A Starfish-compatible voice ID.
input_type	string	No	"text"	"text" for plain text or "ssml" for SSML markup.
speed	number	No	1.0	Speed multiplier (0.5–2.0).
language	string	No	auto-detected	Base language code (e.g. "en", "pt", "zh"). Auto-detected when omitted.
locale	string	No	—	BCP-47 locale tag (e.g. "en-US", "pt-BR"). Overrides language when set.

Response Fields

Field	Type	Description
audio_url	string	URL of the generated audio file.
duration	number	Duration of the audio in seconds.
request_id	string or null	Unique identifier for this generation request.
word_timestamps	array or null	Word-level timing data — each entry has word, start, and end in seconds.

SSML Support

For finer control over pronunciation, pauses, and emphasis, set input_type to "ssml". Check support_pause on the voice object from GET /v3/voices to confirm the voice supports SSML break tags.

curl -X POST "https://api.heygen.com/v3/voices/speech" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "<speak>Welcome to HeyGen. <break time=\"500ms\"/> Let us get started.</speak>",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
    "input_type": "ssml"
  }'