# Quick Example

```bash
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**

```json
{
  "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 }
    ]
  }
}
```

# Finding a Compatible Voice

Before calling this endpoint, find a Starfish-compatible `voice_id`:

```bash
curl -X GET "https://api.heygen.com/v3/voices?engine=starfish&language=English&gender=female" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

See [Browse Voices](/content/docs/voices/search-voices/index.html) for full filtering and pagination details.

# Parameters

| Parameter     | Type   | Required | Default | Description                                          |
|---------------|--------|----------|---------|------------------------------------------------------|
| `text`       | string | Yes      | —       | Text to synthesize (1–5,000 characters).           |
| `voice_id`   | string | Yes      | —       | A Starfish-compatible voice ID.                     |
| `input_type` | string | No       | "text" | "text" for plain text or "ssml" for SSML markup. |
| `speed`      | number | No       | `1.0`   | Speed multiplier (0.5–2.0).                         |
| `language`   | string | No       | auto-detected | Base language code (e.g. "en", "pt", "zh"). Auto-detected when omitted. |
| `locale`     | string | No       | —       | BCP-47 locale tag (e.g. "en-US", "pt-BR"). Overrides `language` when set. |

# Response Fields

| Field           | Type                  | Description                                       |
|-----------------|----------------------|---------------------------------------------------|
| `audio_url`     | string               | URL of the generated audio file.                  |
| `duration`      | number               | Duration of the audio in seconds.                 |
| `request_id`    | string or null       | Unique identifier for this generation request.    |
| `word_timestamps` | array or null      | Word-level timing data — each entry has `word`, `start`, and `end` in seconds. |

# SSML Support

For finer control over pronunciation, pauses, and emphasis, set `input_type` to "ssml". Check `support_pause` on the voice object from `GET /v3/voices` to confirm the voice supports SSML break tags.

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