Third Party Speech

Convert text to audio with any catalog voice on the HeyGen Voice, Starfish, or ElevenLabs engine. HeyGen Voice clones speak through Text to Speech instead.

Full schema: POST /v3/voices/speech.

This endpoint synthesizes any voice from the voice catalog: stock voices and designed voices. Most stock voices run on the HeyGen Voice engine. For a HeyGen Voice clone, instant or professional, use Text to Speech on POST /v3/models/audio/tts instead.

Engines

Pick the engine per request with engine, or omit it to use the voice’s saved default. The response’s engine field reports which one ran.

engine	Engine	Default for
orca	HeyGen Voice	Most public catalog voices
starfish	Starfish (HeyGen)	Voices without a saved engine
elevenlabs	ElevenLabs	Voices saved to ElevenLabs

ElevenLabs models, set with settings.model_id: eleven_v4, eleven_v3, eleven_multilingual_v2, eleven_flash_v2_5, eleven_flash_v2, eleven_turbo_v2_5. Starfish takes locale (e.g. zh-HK); ElevenLabs takes language.

Each voice lists the engines it can use in available_engines and its saved default in default_engine on GET /v3/voices. Filter the catalog with ?engine=orca, ?engine=starfish, or ?engine=elevenlabs.

Quick example

Pick a voice with GET /v3/voices (see Browse Voices), then pass its voice_id:

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,
    "engine": "orca",
    "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 }
    ]
  }
}

Choose an engine

Set engine for this request only. For ElevenLabs, add settings.model_id:

ElevenLabs v4

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",
    "engine": "elevenlabs",
    "settings": { "model_id": "eleven_v4" }
  }'

The engine you ask for is the engine that runs. A 400 means the voice, your plan, or the requested language can’t use it; pick another from the voice’s available_engines. A 403 ai_vendor_access_restricted means a workspace admin has blocked ElevenLabs. The older engine: "elevenlabs_v3" still works; new integrations pass engine: "elevenlabs" with settings.model_id.

text takes 1–5,000 characters. Optional fields: speed (0.5–2.0, default 1.0), language (base code such as en, auto-detected when omitted), locale (BCP-47 tag such as pt-BR, which overrides language), and force_regenerate (skip the speech cache for fresh audio). Keep input_type at its default text; <break> tags work directly in plain text.

Adding pauses

Insert <break> where you want a pause, with the time in seconds:

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

<break> is the only markup to include; wrapping the script in other tags such as <speak> can add spoken artifacts. Check support_pause on the voice in GET /v3/voices first. The same tag works in script text passed to POST /v3/videos.