> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<img className="w-full h-44 object-cover rounded-xl" src="https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-2.webp?fit=max&auto=format&n=hfMXXwJzjE7vBSYZ&q=85&s=d6ee10585b27ddaf8137d6ed67791708" alt="" noZoom width="1400" height="788" data-path="images/theme/research-2.webp" />

Full schema: [`POST /v3/voices/speech`](/reference/generate-speech).

This endpoint synthesizes any voice from the [voice catalog](/docs/voices/overview): stock voices and [designed voices](/docs/voices/design-voices). Most stock voices run on the HeyGen Voice engine. For a HeyGen Voice clone, [instant](/docs/voices/heygen-voice-instant-clone) or [professional](/docs/voices/professional-voice-clone), use [Text to Speech](/docs/voices/heygen-voice-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`](/reference/list-voices). Filter the catalog with `?engine=orca`, `?engine=starfish`, or `?engine=elevenlabs`.

## Quick example

Pick a voice with [`GET /v3/voices`](/reference/list-voices) (see [Browse Voices](/docs/voices/search-voices)), then pass its `voice_id`:

```bash theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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`:

<CodeGroup>
  ```bash ElevenLabs v4 theme={null}
  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" }
    }'
  ```

  ```bash HeyGen Voice theme={null}
  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": "orca"
    }'
  ```

  ```bash Starfish theme={null}
  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": "starfish",
      "locale": "en-US"
    }'
  ```
</CodeGroup>

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:

```bash theme={null}
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`](/reference/list-voices) first. The same tag works in `script` text passed to [`POST /v3/videos`](/reference/create-video).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.