Text to Speech

Full schema: POST /v3/voices/speech. This endpoint synthesizes voices from the voice catalog on the Starfish engine: stock voices, designed voices, and HeyGen instant clones. For a professional HeyGen Voice clone, use HeyGen Voice Speech.

Quick example

Pick a Starfish-compatible voice with GET /v3/voices?engine=starfish (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,
    "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 }
    ]
  }
}

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), and locale (BCP-47 tag such as pt-BR, which overrides language). 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.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Video Translation

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Socials

For Agents

Integrations

Quick example

Adding pauses

​Quick example

​Adding pauses

Quick example

Adding pauses