Models

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].

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. For paid models, API-key billing accumulates fractional usage. OAuth requests, including MCP calls, are rounded up per request to whole billing units, so their effective cost can be higher.

seed, speed, pitch_shift, and pitch_variance apply only to professional clones. Instant clones, including Turbo, accept and ignore these controls.

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. This response has no Retry-After header. Retry the request with exponential backoff. 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.

POST

models

audio

tts

stream

Stream Speech

curl --request POST \
  --url https://api.heygen.com/v3/models/audio/tts/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "language": "en",
  "text": "Hello from HeyGen Voice.",
  "voice_id": "<voice_id>"
}
'

import requests

url = "https://api.heygen.com/v3/models/audio/tts/stream"

payload = {
    "language": "en",
    "text": "Hello from HeyGen Voice.",
    "voice_id": "<voice_id>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({language: 'en', text: 'Hello from HeyGen Voice.', voice_id: '<voice_id>'})
};

fetch('https://api.heygen.com/v3/models/audio/tts/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/models/audio/tts/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'language' => 'en',
    'text' => 'Hello from HeyGen Voice.',
    'voice_id' => '<voice_id>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/models/audio/tts/stream"

	payload := strings.NewReader("{\n  \"language\": \"en\",\n  \"text\": \"Hello from HeyGen Voice.\",\n  \"voice_id\": \"<voice_id>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.heygen.com/v3/models/audio/tts/stream")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"language\": \"en\",\n  \"text\": \"Hello from HeyGen Voice.\",\n  \"voice_id\": \"<voice_id>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/models/audio/tts/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"language\": \"en\",\n  \"text\": \"Hello from HeyGen Voice.\",\n  \"voice_id\": \"<voice_id>\"\n}"

response = http.request(request)
puts response.read_body

{
  "type": "audio",
  "part_index": 1,
  "audio": "<string>"
}

Authorizations

x-api-key

string

header

required

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json

voice_id

string

required

Identifier of the voice used for speech synthesis.

Minimum string length: 1

text

string

required

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. 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.

Required string length: 1 - 5000

end_user_id

string | null

Stable, 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.

Required string length: 1 - 128

Pattern: ^\S+$

output_format

SpeechOutputFormat · object | null

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.

Show child attributes

model

enum<string>

default:heygen-voice-1

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.

Available options:

heygen-voice-1,

heygen-voice-1-turbo,

heygen-voice-1-turbo-free

pronunciation_dictionary

Pronunciation Dictionary · object | null

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.

Show child attributes

language

string | null

Language code of text. Regional tags normalize to their supported base language, such as en-US to en. 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.

Minimum string length: 1

previous_request_ids

string[] | null

Completed 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.

Maximum array length: 3

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9_-]+$

next_request_ids

string[] | null

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.

Maximum array length: 3

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9_-]+$

expressiveness_boost

number | null

Expressiveness boost for instant voices, from 0.0 to 1.0. Omit for professional voices. Omitted values use 0.5 with pronunciation and 1.0 otherwise.

Required range: 0 <= x <= 1

seed

integer | null

Optional best-effort deterministic generation seed for professional clones. Ignored for instant clones.

Required range: 0 <= x <= 4294967295

speed

number | null

Speech speed multiplier for professional clones. Ignored for instant clones, including Turbo.

Required range: 0.75 <= x <= 1.25

pitch_shift

number | null

Pitch shift in semitones for professional clones. Ignored for instant clones.

Required range: -4 <= x <= 4

pitch_variance

number | null

Pitch variation multiplier for professional clones; 1.0 preserves the voice default. Ignored for instant clones.

Required range: 0.5 <= x <= 2

with_timestamps

boolean

default:false

Include character and word timings after the audio.

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.

type

string

required

Event type.

Allowed value: "audio"

part_index

integer

required

Zero-based sequence number of this audio part.

Required range: x >= 0

audio

string

required

Base64-encoded standalone WAV audio part.

⌘I

Stream Speech

curl --request POST \
  --url https://api.heygen.com/v3/models/audio/tts/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "language": "en",
  "text": "Hello from HeyGen Voice.",
  "voice_id": "<voice_id>"
}
'

import requests

url = "https://api.heygen.com/v3/models/audio/tts/stream"

payload = {
    "language": "en",
    "text": "Hello from HeyGen Voice.",
    "voice_id": "<voice_id>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({language: 'en', text: 'Hello from HeyGen Voice.', voice_id: '<voice_id>'})
};

fetch('https://api.heygen.com/v3/models/audio/tts/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/models/audio/tts/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'language' => 'en',
    'text' => 'Hello from HeyGen Voice.',
    'voice_id' => '<voice_id>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/models/audio/tts/stream"

	payload := strings.NewReader("{\n  \"language\": \"en\",\n  \"text\": \"Hello from HeyGen Voice.\",\n  \"voice_id\": \"<voice_id>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.heygen.com/v3/models/audio/tts/stream")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"language\": \"en\",\n  \"text\": \"Hello from HeyGen Voice.\",\n  \"voice_id\": \"<voice_id>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/models/audio/tts/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"language\": \"en\",\n  \"text\": \"Hello from HeyGen Voice.\",\n  \"voice_id\": \"<voice_id>\"\n}"

response = http.request(request)
puts response.read_body

{
  "type": "audio",
  "part_index": 1,
  "audio": "<string>"
}

Video Agent

Brand

Avatars

Audio

Voices

Models

Videos

Templates

Video Translate

Lipsync

HyperFrames

User

API Keys

Webhooks

Folders

Assets

AI Clipping

Filler Word Removal

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

Stream Speech

Voice and settings

Turbo Free

Language

Limits and request ID

Authorizations

Body

Response