The HeyGen Voice model speaks two ways from the same request body:
POST /v3/models/audio/ttswaits for synthesis and returns one audio file URL. By default, the file is a 44.1 kHz WAV.POST /v3/models/audio/tts/streamreturns ordered audio parts as Server-Sent Events (SSE).
text in pieces, such as LLM tokens, use WebSocket input streaming.
To get MP3, raw PCM, μ-law, or A-law audio, or a different sample rate, set output_format.
voice_id must be an ACTIVE HeyGen public voice or a clone in your workspace: an instant voice or a professional clone.
Generate speech with an agent
Paste this into Claude Code, Codex, or Cursor to try Turbo Free with a public voice. You do not need to create a clone or add credits.Prompt for your agent
Turbo Free
HeyGen Voice Turbo Free is free until November 30, 2026. We will notify you before this offer changes.Try it in the playground · Get a free API key
"model": "heygen-voice-1-turbo-free" on either speech endpoint, or model=heygen-voice-1-turbo-free on a WebSocket. These requests are free and do not require a credit balance.
Use a public voice or a HeyGen Voice 1 instant clone. Professional clones are not supported.
Requests to the default model or paid Turbo are still charged.
Use Turbo Free for tests, prototypes, and small amounts of speech.
Service availability, response time, and time to first audio are not guaranteed.
Speech limits
Two limits apply:- Your request limit: each endpoint allows 30 requests per minute per workspace member by default. Your account can have a different limit.
- Shared capacity: all Turbo Free users share a limited amount of capacity. You can receive HTTP
429even if you are below your request limit.
429 rate_limit_exceeded.
If the response has a Retry-After header, wait that number of seconds before you retry.
Otherwise, increase the wait time after each failed attempt (exponential backoff).
A timeout or service failure can return HTTP 500 instead.
For streaming requests, these HTTP errors occur before audio starts.
A free request never switches to a paid model.
To use paid Turbo, send a new request with "model": "heygen-voice-1-turbo". This request is charged.
Request fields
The full field list is in the API reference.text takes 1–10,000 characters of plain prose, and public and instant voices also perform audio tags, such as [laughs], and take IPA pronunciations. model defaults to heygen-voice-1; null and unknown names return 400. expressiveness_boost (instant voices, 0.0–1.0, default 1.0, or 0.5 when a pronunciation applies) is not applied when text contains an audio tag other than [pause]. seed, speed, pitch_shift and pitch_variance shape professional voices only.
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 on heygen-voice-1 take <break time="0.5s"/> pauses of up to 5 seconds each. On an instant voice, including every Turbo request, a <break> tag returns 400 invalid_parameter. Other SSML is not supported. Instant voices made before HeyGen Voice 1 must be cloned again before they can speak here.
Language
Sendlanguage as a lowercase ISO 639-1 code from Supported languages, such as en or zh. HeyGen Voice has no regional accents, so a regional tag such as en-US, pt-BR, or zh-HK returns 400 invalid_parameter with param set to language; send the base code instead. Cantonese (yue) is not supported.
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 returns400 invalid_parameter. - The language the voice was created in, if
textis written in that language’s script. - A less certain reading, if a second reading of
textagrees with it. - The usual language of the script
textis written in, such as English for Latin letters.
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.
Supported languages
fil is also accepted for Filipino.
Generate completed speech
Try Turbo Free with Nadine, a public voice. No clone or credit balance is required. The same voice and model work in the streaming example below.audio_url, one mono PCM16 WAV at 44.1 kHz without output_format, and duration in seconds.
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.
For a professional voice, swap the instant-only control for the prosody controls:
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.
original_characters follows text as sent, so it also covers the characters of any audio tags. Leave the bracketed tags out when you build captions.
Timestamps don’t change the price.
Stream speech
The stream istext/event-stream. Disable response buffering and handle each event as it arrives.
part_index order; each part is a complete WAV container, so decode them individually rather than concatenating the bytes.
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: [DONE]. If synthesis fails mid-stream, the stream ends with an error event instead and no [DONE]:
WebSocket input streaming
Use a WebSocket when your text arrives in pieces, such as tokens from an LLM. You send text as it is produced. Audio returns on the same connection.
Messages use the ElevenLabs
stream-input and multi-stream-input formats. The URLs, authentication, and parameter names are HeyGen’s, so ElevenLabs SDKs do not connect directly.
Use a public voice or an instant clone on any of the three models. A professional clone returns 400 invalid_parameter at the handshake. Use POST /v3/models/audio/tts/stream for those voices.
Send text and receive audio
This Python example useswebsockets and writes raw PCM16 at 24 kHz to speech.pcm.
Authenticate
Send the sameX-Api-Key or Authorization: Bearer header as the other speech endpoints. An API key needs the voices:write scope.
A client that cannot set headers, such as a browser, uses a single-use token. Your backend calls POST /v3/models/audio/tts/stream-input/tokens with its API key. The client then adds the returned token to the URL:
Query parameters
voice_id is required. Unknown parameters return 400 invalid_parameter at the handshake.
Messages you send
Send JSON text messages. An unknown field closes the socket with code1008.
On
multi-stream-input, a context stays open after flush, so you can send it more text. Send close_context to end it. A context that you do not close ends after inactivity_timeout. It counts toward the five running contexts until then.
Messages you receive
Each audio message carries base64 audio inoutput_format. alignment follows the text as sent, and normalizedAlignment follows the text spoken. Both are null when timings are off or not available, and their lists can be empty on a message. Times are in milliseconds from the start of that message.
isFinal: true. synthesizedChars is the number of characters spoken, so it is lower when a context stops early.
multi-stream-input, every message also has contextId. A JSON message with message and the standard error envelope comes before every close except codes 1000 and 1012.
Socket limits
- Request limit: each handshake and each token request counts as one request toward the Stream Speech limit. On
multi-stream-input, each new context counts as one more. Past the limit, a handshake returns429 rate_limit_exceededwithRetry-After, and a new context closes the socket with code1008. - Context size: each context accepts up to 10,000 characters and is billed as one request.
- Turbo Free: a request is counted when each context opens. Text is counted as each piece is sent for synthesis. A socket over the free quota closes with code
1008, which can come after earlier audio. - Open sockets: a workspace can have a limit on open sockets. Past it, a handshake returns
429 rate_limit_exceededwithRetry-After.
Close codes
A refused handshake returns the standard error envelope. After the handshake, the socket reports problems with a close code:Output format
Withoutoutput_format, /tts returns a WAV file and /tts/stream returns SSE events with WAV parts. Both are mono PCM16 at 44.1 kHz.
Set output_format on either endpoint to choose the encoding (pcm, mp3, ulaw or alaw) and sample_rate_hertz. All output is mono. pcm is signed little-endian PCM16 with no header, and ulaw and alaw run at 8000 Hz only. pcm and mp3 default to 44100 Hz; the allowed rates and mp3 bitrate_bps values are in the API reference. An unsupported combination, such as ulaw at 16000 Hz, returns 400 invalid_parameter.
On /tts, audio_url is a file in the requested format. Its extension names the encoding: .pcm, .mp3, .ulaw, or .alaw. The pcm, ulaw, and alaw files contain only audio samples, with no WAV header. To get a WAV file, omit output_format.
/tts/stream, the response body is raw audio bytes in the requested format, not SSE. The stream has no events and no [DONE]. Write the bytes to a file or a player in the order they arrive.
Content-Typeisaudio/pcm,audio/mpeg,audio/basic(μ-law), oraudio/alaw.- The
X-Audio-Sample-RateandX-Audio-Channelsheaders give the sample rate and the number of channels. with_timestampsmust befalse. If it istrue, the request returns400 invalid_parameter.- If synthesis fails after the audio starts, the connection closes. No error event is sent.
Audio tags
Write an audio tag, such as[excited], [whispers], or [laughs], in text to change how a public or instant voice speaks, or to add a sound at that spot. Both speech endpoints accept them on all three models. See Audio Tags for samples, the 201 supported tags, and how to write them.
Pronunciation
Set how a public or instant voice says a name or term with an IPA transcription. Pronunciation works onheygen-voice-1 and heygen-voice-1-turbo, on both speech endpoints.
For every occurrence of a term, send pronunciation_dictionary, an object of up to 100 terms, each mapped to its IPA:
<pron> tag in text:
- Write each IPA value between slashes, as in
/ʃɪˈvɔːn/, in up to 512 characters. - A dictionary term matches whole words, without regard to case, so
Keytrudaalso matchesKEYTRUDA. A term can be up to 128 characters. - A
<pron>tag takes precedence over the dictionary for the text it wraps. - A request can apply up to 100 pronunciations, counting every occurrence from the dictionary and from tags.
- When a pronunciation applies,
expressiveness_boostdefaults to0.5. Send it to choose another value from0.0to1.0.
brand_glossary_id. Text to Speech takes them with each request in pronunciation_dictionary.
Pronunciation requests that cannot be served return 400 invalid_parameter:

