Stream Speech
Stream speech from the voice identified by voice_id.
Set output_format to request raw PCM16, MP3, mu-law, or A-law audio bytes without SSE framing. Raw streams require with_timestamps=false; a failure after audio begins terminates the connection. X-Audio-Sample-Rate and X-Audio-Channels identify the audio parameters.
Otherwise, the response sends base64 WAV parts as Server-Sent Events (SSE). Set with_timestamps to true to include one alignment event after the audio. This event contains character and word timings for original and normalized text. Words use Unicode boundaries, without dictionary segmentation. A successful stream ends with data: [DONE].
WebSocket input streaming
To send text in pieces as it is produced, such as LLM tokens, open a WebSocket instead. Use wss://api.heygen.com/v3/models/audio/tts/stream-input?voice_id=<voice_id> for one synthesis, or wss://api.heygen.com/v3/models/audio/tts/multi-stream-input?voice_id=<voice_id> for up to five concurrent contexts on one socket. Messages use the ElevenLabs stream-input and multi-stream-input formats: send {"text": " "} to open, then the text pieces, flush to generate what is buffered, and {"text": ""} to end the input. Audio returns as base64 audio messages in output_format (default pcm_44100).
Authenticate the handshake with the same headers as this endpoint. A client that cannot set headers, such as a browser, calls POST /v3/models/audio/tts/stream-input/tokens and passes the returned token as a query parameter. A token is valid for 15 minutes and for one connection.
Query parameters use the names of this endpoint, such as model, language, and with_timestamps. The sockets serve instant clones on heygen-voice-1, heygen-voice-1-turbo, and heygen-voice-1-turbo-free, and refuse professional clones. Each context accepts up to 10,000 characters and is billed as one request. On a socket, Turbo Free counts a request when each context opens and counts text as each piece is sent for synthesis. A socket over the free quota closes with code 1008, which can come after earlier audio.
A workspace can have a limit on open sockets, at most the API concurrency of its plan. Sockets opened with an API key count against the API plan, and sockets opened by an OAuth app count against the web plan, each separately. The limit is off by default. When it is on, a handshake past the limit gets HTTP 429 with code=rate_limit_exceeded and a Retry-After header. Retry that handshake after the Retry-After time.
Voice and settings
Use an ACTIVE HeyGen Voice clone in your workspace. heygen-voice-1-turbo speaks instant clones at lower latency and refuses professional clones.
seed, speed, pitch_shift, and pitch_variance apply to instant and professional clones. Omit seed for a random seed. Send the same seed again to try to repeat a result; repeats are best effort.
Turbo Free
Use heygen-voice-1-turbo-free for instant voices without charge, including API-key and OAuth requests. This model is available to direct users and resellers for experimentation and prototyping. It has no latency, time-to-first-audio, or availability guarantee.
Per-user request limits and shared free capacity both apply. Either limit can return HTTP 429 with code=rate_limit_exceeded. Shared capacity can be exhausted even when you are below your own request limit. A timeout or service failure can return HTTP 500. Follow Retry-After when present; otherwise use exponential backoff. A free request never switches to a paid model. For streaming, HTTP 429 is returned before audio starts.
Language
Set language to the language of text. If you omit it, the language is detected from text. Successful responses include Content-Language, the language the speech was generated in.
Limits and request ID
The rate limit is 30 requests per minute per workspace member.
High demand can exceed the available capacity for speech generation. The service then returns HTTP 429 with code=rate_limit_exceeded and no Retry-After header. Retry the request with exponential backoff. The socket-limit handshake response also has code=rate_limit_exceeded, but it has Retry-After. For streaming, the service returns HTTP 429 only before the response starts.
Successful responses include X-Request-Id. Use this ID when you contact support about the request. For instant clones, completed requests automatically retain audio for request stitching when speech retention is allowed. Pass completed IDs in previous_request_ids or next_request_ids to keep continuity. Use up to three IDs per field in playback order, from the same workspace, voice, and model, within two hours. Finish reading a stream before reusing its ID. If context is unavailable, synthesis continues with its normal defaults. Stitching is unavailable when speech retention is disabled.
Body
Text to synthesize. Instant voices accept caller-supplied IPA, such as Acme. Respelling cues are not supported. Unsupported IPA returns HTTP 400. Pronunciation requires an available pronunciation-capable model. Instant voices perform audio tags in square brackets, such as [laughs], [whispers], or [sad]; see https://developers.heygen.com/docs/voices/heygen-voice-speech#audio-tags for the supported tags. Bracketed text that is not a supported tag is usually not spoken; to have those words spoken, remove the square brackets. Professional voices do not perform audio tags. Professional voices accept pauses (seconds, up to 5 per pause, e.g. ); other SSML, and break tags for an instant voice clone, are not supported.
1 - 10000Stable, opaque end-user identifier in your application, scoped to the authenticated workspace. Use 1–128 non-whitespace characters without personal information. Used for usage attribution and abuse investigation; does not change billing, authorization, or rate limits.
1 - 128^\S+$Optional audio output: encoding pcm (signed little-endian PCM16), mp3, ulaw, or alaw; mono only. sample_rate_hertz: 8000, 16000, 22050, 24000, 44100, or 48000 for pcm/mp3 (default 44100); ulaw/alaw require 8000 (default). MP3 bitrate_bps: 32000/48000/64000 below 32000 Hz (default 64000), or 64000/96000/128000/192000 at 44100/48000 Hz (default 128000). Omit for the existing WAV file or SSE stream of base64 WAV parts. When supplied, /tts/stream returns raw audio bytes and does not support with_timestamps.
heygen-voice-1: instant and professional voices. heygen-voice-1-turbo: instant voices at lower latency. heygen-voice-1-turbo-free: instant voices without charge, subject to per-user limits and shared capacity. No latency or availability guarantee. Requests rejected by a limit or capacity check return HTTP 429. Timeouts and service failures can return HTTP 500.
heygen-voice-1, heygen-voice-1-turbo, heygen-voice-1-turbo-free Text normalization rewrites numbers, currencies, dates, and other written forms as spoken words before synthesis. Applies to instant voices, including Turbo, and professional voices. on normalizes text in Arabic, Chinese, English, French, German, Hebrew, Hindi, Indonesian, Italian, Japanese, Korean, Portuguese, Russian, Spanish, and Vietnamese; text in any other language is spoken as written. off speaks all text as written. auto (default) lets HeyGen Voice decide and currently behaves as on. Pronunciation dictionaries, inline IPA, audio tags, and break tags are not affected.
auto, on, off Optional term-to-IPA dictionary, such as {"Acme": "/ˈækmi/"}. Use enclosing slashes for each IPA value. Matches whole terms without case sensitivity. Inline pronunciation takes precedence. Supports instant voices on heygen-voice-1 and heygen-voice-1-turbo when pronunciation is available. Omit expressiveness_boost to use 0.5, or supply a value from 0.0 to 1.0.
Language of text as a lowercase ISO 639-1 code, such as en or zh. HeyGen Voice has no regional accents, so a regional tag such as en-US or zh-HK fails with invalid_parameter. Omit it to detect the language from text. A confident reading that matches the letters of text is used, and the request fails with invalid_parameter if HeyGen Voice does not speak that language. Otherwise the first of these that HeyGen Voice speaks is used: the language the voice was created in, if text is written in that language's script; a less certain reading that a second reading of text without its numbers and brand names agrees with; the usual language of the script text is mostly written in, such as English for Latin letters; and, only when that script has no usual language, the reading itself. If none of them applies, the request fails with invalid_parameter. The Content-Language response header names the language used.
ar, be, bg, ca, cs, da, de, el, en, es, fa, fi, fr, he, hi, hr, hu, id, it, ja, ko, mk, ms, nl, pl, pt, ro, ru, sk, sl, sr, sv, ta, th, tl, tr, uk, vi, zh 1Completed speech request IDs before this text, in playback order, up to three. Use X-Request-Id from completed batch or fully consumed streaming responses within two hours. Requests must use the same workspace, voice, and model. Instant clones only, including Turbo. Unavailable when speech retention is disabled. Only the last three seconds of context are used. Unavailable context falls back to normal synthesis.
31 - 64^[A-Za-z0-9_-]+$Completed speech request IDs after this text, in playback order, up to three. Use X-Request-Id from completed batch or fully consumed streaming responses within two hours. Requests must use the same workspace, voice, and model. Instant clones only, including Turbo. Unavailable when speech retention is disabled. Only the first three seconds of context are used. Unavailable context falls back to normal synthesis.
31 - 64^[A-Za-z0-9_-]+$Response
Raw audio bytes when output_format is supplied; otherwise a Server-Sent Events stream. Each data: frame contains an audio, alignment, or terminal error event; a clean stream terminates with data: [DONE].
- SpeechAudioEvent
- SpeechCharacterAlignmentEvent
- SpeechErrorEvent
One JSON event carried by the speech SSE stream.

