HEheygen
Voices

Generate Speech

Changed on

Synthesizes speech from text with a catalog voice and returns an audio URL, its duration and optional word timestamps. Omit engine to use the voice's saved default and settings, or set it per request; choose an ElevenLabs model with settings: {model_id: 'eleven_v4'}. Requests that omit engine use HeyGen Voice for most public catalog voices. Set engine: 'heygen_voice' to explicitly request HeyGen Voice, or 'starfish' for Starfish. The legacy 'orca' input remains accepted; response engine values retain 'orca' for compatibility. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead. HTTP 400: the saved default or explicit engine is unsupported, not allowed on your plan, or incompatible with the requested locale or language. HTTP 403 (ai_vendor_access_restricted): workspace vendor policy blocks ElevenLabs and all of its model variants.

post/v3/voices/speech

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/voices/speech
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Request body

textstring required

Text to synthesize (1-5000 characters). Break tags must express time in seconds (for example, <break time="0.35s"/>); millisecond values are not supported.

voice_idstring required

Voice ID from the voice catalog. Professional voice clones use model speech generation instead.

input_typestring

Type of the input: 'text' for plain text, 'ssml' for SSML markup. Defaults to 'text'.

speednumber

Speed multiplier (0.5-2.0).

languagestring nullable

Base language code (e.g. 'en', 'pt', 'zh'). Optional — auto-detected from text when omitted.

localestring nullable

Locale tag for Starfish (e.g. 'zh-HK'). ElevenLabs does not support locale selection; use language instead.

force_regenerateboolean

Bypass HeyGen's speech cache and request fresh synthesis. Normal speech quota applies. Defaults to false.

engine'heygen_voice' | 'starfish' | 'orca' | 'elevenlabs' | 'elevenlabs_v3' nullable

Speech engine override for this request only. Omit to use the voice's saved default, including your saved preference. Voices without a concrete saved default retain Starfish. Unsupported defaults or overrides return an error; engines are never silently substituted. Use 'heygen_voice' for HeyGen Voice; 'orca' remains accepted as its legacy alias. Responses retain 'orca' for compatibility. ElevenLabs model variants are selected through settings.model_id. The deprecated elevenlabs_v3 input is accepted and runs as elevenlabs with the voice's saved V3 model (eleven_v3 or eleven_v4) unless settings.model_id names one; responses report elevenlabs.

Response

Successful response

Example response

{
  "data": {
    "audio_url": "https://files.heygen.ai/audio/tts_abc123.mp3",
    "duration": 4.5,
    "request_id": "req_abc123",
    "word_timestamps": [
      {
        "word": "Hello",
        "end": 0.35
      }
    ]
  }
}

Changes

  • 7dfa5e59b4f5Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the required property / to the response with the status