---
title: "Generate speech audio from text"
method: POST
path: "/v1/audio/text_to_speech"
tags: ["Voices"]
---

# Generate speech audio from text

`POST /v1/audio/text_to_speech`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v1/audio/text_to_speech`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Synthesize speech audio from text using a specified voice. Returns a URL to the generated audio file along with duration and optional word-level timestamps.

## Request body

- TextToSpeechRequest: Request body for text-to-speech generation.
  - `text` string, 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_id` string, required: Voice ID from the voice catalog. The voice must be one the Starfish engine supports: a stock voice, a designed voice, or an instant clone. List them with GET /v3/voices?engine=starfish. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead.
  - `input_type` string: Type of the input: 'text' for plain text, 'ssml' for SSML markup. Defaults to 'text'.
  - `speed` number: Speed multiplier (0.5-2.0).
  - `language` string, nullable: Base language code (e.g. 'en', 'pt', 'zh'). Optional — auto-detected from text when omitted.
  - `locale` string, nullable: BCP-47 locale tag (e.g. 'en-US', 'pt-BR'). When set, language is inferred from locale.

## Response `200`

Successful response

- object
  - `data` TextToSpeechResponseData: Response payload for text-to-speech generation.
    - `audio_url` string, required: URL of the generated audio file.
    - `duration` number, required: Duration of the audio in seconds.
    - `request_id` string, nullable: Unique identifier for this generation request.
    - `word_timestamps` WordWithTimestamp[], nullable: Word-level timing data.
      - `word` string, required: The word.
      - `start` number, required: Start time in seconds.
      - `end` number, required: End time in seconds.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v1/audio/text_to_speech/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)