Text to Speech

Recommended settings for voice identity. For the closest match to the original speaker’s voice, set similarity: "max" when you create the instant voice clone and expressiveness_boost: 0.5 when you generate speech. These are the defaults HeyGen Studio uses.The API defaults are different: similarity: "extra_high" for voice cloning and expressiveness_boost: 1.0 for speech. That configuration took first place on the Artificial Analysis Controlled Voice leaderboard.

The HeyGen Voice model speaks two ways from the same request body:

POST /v3/models/audio/tts waits for synthesis and returns one 44.1 kHz WAV URL.
POST /v3/models/audio/tts/stream returns ordered audio parts as Server-Sent Events (SSE).

voice_id must be an ACTIVE HeyGen Voice clone in your workspace: an instant voice or a professional clone. Each endpoint allows 30 requests per minute per workspace member.

Generate speech with an agent

Not technical? Paste this into Claude Code, Codex, or Cursor and it generates speech from your voice with you, in your own terminal. To make the voice first, start from the Instant Clone or Professional Clone prompt.

Prompt for your agent

I have a HeyGen Voice clone (instant or professional) and want to generate speech with it. I am not a developer, so run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/docs/voices/heygen-voice-speech.md
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then take me through this, checking each step before the next:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me.
2. Voice. List my voices with GET /v3/models/audio/voices, and HeyGen's public voices with GET /v3/models/audio/voices?type=public. Show me each name, mode and status. Use the one I pick; it must be ACTIVE.
3. Text. Ask me what I want the voice to say, up to 5,000 characters of plain prose, and its language if I know it.
4. Speak. Call POST /v3/models/audio/tts with model heygen-voice-1, the voice_id and text. Send language only if I told you the language; otherwise leave it out so HeyGen detects it. Download the WAV and open it so I can listen. Show me how to change the text and run it again. If the voice's mode is professional, also show me how to keep the delivery the same across runs with a seed. Omit seed, speed and pitch for an instant voice; these controls are ignored.

If a request fails, look the error code up in the Errors table on that page and tell me the fix. Never invent keys, IDs, or URLs; if something is missing, ask me for that one thing.

Successful completed and streaming responses include X-Request-Id and Content-Language. Use X-Request-Id to match usage records and any billing settlement. Content-Language names the language the speech was generated in.

Request fields

Field	Type	Required	Description
`model`	string	No	`heygen-voice-1` (default) speaks instant and professional voices. `heygen-voice-1-turbo` speaks instant voices at lower latency. `null` and other names return `400`.
`voice_id`	string	Yes	An `ACTIVE` instant or professional voice owned by the API key’s workspace, or a HeyGen public voice from `GET /v3/models/audio/voices?type=public`.
`text`	string	Yes	Plain prose to synthesize, 1–5,000 characters.
`language`	string	No	Language code of `text`, such as `en`. Regional tags normalize to the base language. Omit it to detect the language from `text`; see Language. See the supported languages.
`expressiveness_boost`	number	No	Instant voices only. `0.0`–`1.0`, default `1.0`.
`seed`	integer	No	Ignored for instant voices. For professional voices: best-effort deterministic seed, `0`–`4294967295`.
`speed`	number	No	Ignored for instant voices. For professional voices: speech speed multiplier from `0.75` to `1.25`.
`pitch_shift`	number	No	Ignored for instant voices. For professional voices: shifts pitch from `-4` to `+4` semitones.
`pitch_variance`	number	No	Ignored for instant voices. For professional voices: pitch variation from `0.5` to `2.0`; `1.0` keeps the default.
`with_timestamps`	boolean	No	Default `false`. On `/tts`, adds `original_characters` to the response; see Character timestamps. On `/tts/stream`, adds character-alignment events.

Unknown fields and invalid values return 400 invalid_parameter, with param set to that field. Instant voices, including Turbo, accept and ignore valid seed, speed, pitch_shift, and pitch_variance values. Professional voices reject expressiveness_boost. Professional voices take <break time="0.5s"/> pauses of up to 5 seconds each; instant voices do not. Other SSML is not supported. Instant voices made before HeyGen Voice 1 must be cloned again before they can speak here.

Language

Send language when you know it. HeyGen speaks text in the stated language as given and does not check it against the text, so a wrong one, such as en for Russian text, gives speech with that language’s accent. If you are not sure, leave it out. When you omit it, HeyGen reads the language from text and uses the first of these that applies:

A confident reading of text. If HeyGen Voice does not speak that language, the request returns 400 invalid_parameter.
The language the voice was created in, if text is written in that language’s script.
A less certain reading, if a second reading of text agrees with it.
The usual language of the script text is written in, such as English for Latin letters.

If none of these is a language HeyGen Voice speaks, the request returns 400 invalid_parameter with param set to language. Send language and try again. Every successful response names the language it used in the Content-Language header, so you can check the result and send language next time if it is not what you meant.

Generate completed speech

curl -X POST "https://api.heygen.com/v3/models/audio/tts" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-voice-1",
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "text": "Hello from my instant voice.",
    "language": "en",
    "expressiveness_boost": 0.8
  }'

Response

{
  "data": {
    "audio_url": "https://files.heygen.ai/generated/model-speech.wav",
    "duration": 3.42
  }
}

The request stays open until the file is assembled, so no polling is needed. audio_url is one mono PCM16 WAV at 44.1 kHz; duration is in seconds.

Character timestamps

Set "with_timestamps": true to get the time of each character, for captions or word highlighting. The response then also carries original_characters: one entry for each character of text, in order, with text, start_time, and end_time in seconds from the start of the audio.

Response

{
  "data": {
    "audio_url": "https://files.heygen.ai/generated/model-speech.wav",
    "duration": 0.42,
    "original_characters": [
      {"text": "H", "start_time": 0.0, "end_time": 0.08},
      {"text": "i", "start_time": 0.08, "end_time": 0.21},
      {"text": "!", "start_time": 0.21, "end_time": 0.35}
    ]
  }
}

Timestamps don’t change the price. Without with_timestamps, the response is the same as above. For a professional voice, swap the instant-only control for the prosody controls:

{
  "model": "heygen-voice-1",
  "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234",
  "text": "Hello from my professional voice. <break time=\"0.5s\"/> Let us begin.",
  "language": "en",
  "seed": 7,
  "speed": 1.1,
  "pitch_shift": -1.0,
  "pitch_variance": 1.2
}

Stream speech

The stream is text/event-stream. Disable response buffering and handle each event as it arrives.

curl -N --no-buffer -X POST "https://api.heygen.com/v3/models/audio/tts/stream" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "heygen-voice-1",
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "text": "Hello from my instant voice.",
    "language": "en",
    "with_timestamps": true
  }'

Audio events carry base64-encoded standalone WAV parts. Play them in ascending part_index order; each part is a complete WAV container, so decode them individually rather than concatenating the bytes.

data: {"type":"audio","part_index":0,"audio":"UklGR..."}

data: {"type":"audio","part_index":1,"audio":"UklGR..."}

Character-alignment events appear when with_timestamps is true. original_characters follows the submitted text, while normalized_characters follows the text spoken after normalization. Each character carries text, start_time, and end_time in seconds.

data: {"type":"character_alignment","original_characters":[{"text":"H","start_time":0.0,"end_time":0.08}],"normalized_characters":[{"text":"H","start_time":0.0,"end_time":0.08}]}

A clean stream ends with data: [DONE]. If synthesis fails mid-stream, the stream ends with an error event instead and no [DONE]:

data: {"type":"error","detail":"Voice inference failed mid-stream"}

Errors before the first event use the standard JSON error envelope.

Errors

HTTP status	Error code	Meaning
`400`	`invalid_parameter`	Missing or unknown field, an invalid value, an unsupported `language` or `model`, `heygen-voice-1-turbo` sent for a professional voice (`param` is `model`), or, when `language` is omitted, a language that could not be detected from `text`.
`400`	`voice_expired`	The workspace is over its professional voice clone slot limit. Add a slot or delete another professional voice.
`402`	`insufficient_credit`	The API credit balance is empty.
`402`	`usage_limit_reached`	The member reached a workspace usage limit. Ask a workspace administrator to check the limit.
`403`	`forbidden`	The voice is a professional clone and the account is not enabled for professional voice cloning. Check the plan on the Usage page.
`404`	`voice_not_found`	The voice is not in the caller’s workspace.
`409`	`voice_not_ready`	The voice is still `PENDING`. Poll `GET /v3/models/audio/voices/{voice_id}` until `status` is `ACTIVE`, then send the request again.
`409`	`voice_training_failed`	The voice is `FAILED`. Read `failure_reason` on the voice.
`429`	`rate_limit_exceeded`	Retry after the seconds in `Retry-After`.
`503`	`service_unavailable`	Inference is busy; the request is safe to retry.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Avatar Management

Voice Management

Video Translation

Lipsync

Tools

Asset Management

Batches

Webhook

Limits

Socials

For Agents

Integrations

Generate speech with an agent

Request fields

Language

Generate completed speech

Character timestamps

Stream speech

Errors

​Generate speech with an agent

​Request fields

​Language

​Generate completed speech

​Character timestamps

​Stream speech

​Errors

Generate speech with an agent

Request fields

Language

Generate completed speech

Character timestamps

Stream speech

Errors