# HeyGen Documentation

HeyGen provides 300+ pre-built voices across dozens of languages, plus the ability to generate custom AI voices from a text description. This guide walks through the full workflow: **browse → design → use**.

## Step 1: Browse Available Voices

Use `GET /v3/voices` to list available voices with cursor-based pagination. Filter by language, gender, type, or engine.

### Example Request

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

### Example Response

```json
{
  "data": [
    {
      "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
      "name": "Sara",
      "language": "English",
      "gender": "female",
      "preview_audio_url": "https://files.heygen.ai/voice/preview/sara.mp3",
      "support_pause": true,
      "support_locale": true,
      "type": "public"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiMTIzIn0"
}
```

### Query Parameters

| Parameter  | Type    | Description                                                                                      |
|------------|---------|--------------------------------------------------------------------------------------------------|
| `type`     | string  | "public" for the shared library or "private" for your cloned voices. Defaults to "public". |
| `engine`   | string  | Filter by voice engine (e.g. "starfish"). Only voices compatible with that engine are returned. |
| `language` | string  | Filter by language name (e.g. "English", "Spanish", "Japanese").                             |
| `gender`   | string  | Filter by "male" or "female".                                                                 |
| `limit`    | integer | Results per page (1–100). Defaults to `20`.                                                    |
| `token`    | string  | Opaque cursor token for the next page.                                                          |

### Response Fields

| Field               | Type         | Description                                                                                                         |
|---------------------|--------------|---------------------------------------------------------------------------------------------------------------------|
| `voice_id`          | string       | Pass this as `voice_id` to video creation endpoints.                                                               |
| `name`              | string       | Display name of the voice.                                                                                         |
| `language`         | string       | Primary language.                                                                                                   |
| `gender`           | string       | Gender of the voice.                                                                                               |
| `preview_audio_url`| string or null| URL to a short audio preview — play to audition the voice.                                                        |
| `support_pause`     | boolean      | Whether the voice supports SSML pause/break tags.                                                                 |
| `support_locale`    | boolean      | Whether the voice supports locale variants.                                                                         |
| `type`             | string       | "public" or "private".                                                                                         |

## Step 2: Design a Custom Voice (Optional)

If none of the pre-built voices fit, use `POST /v3/voices` to generate up to 3 AI voice options from a text description. The endpoint returns a ranked list — pick the one that fits best.

### Example Request

```bash
curl -X POST "https://api.heygen.com/v3/voices" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.", "gender": "male"}'
```

### Example Response

```json
{
  "data": {
    "voices": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
        "name": "James",
        "language": "English",
        "gender": "male",
        "preview_audio_url": "https://files.heygen.ai/voice/preview/james.mp3",
        "support_pause": true,
        "support_locale": true,
        "type": "public"
      }
    ],
    "seed": 0
  }
}
```

### Parameters

| Parameter | Type    | Required | Description                                                                                      |
|-----------|---------|----------|--------------------------------------------------------------------------------------------------|
| `prompt`  | string  | Yes      | Text description of the desired voice — accent, tone, pace, gender, personality. Max 1000 characters. |
| `gender`  | string  | No       | Filter results by "male" or "female".                                                            |
| `locale`  | string  | No       | BCP-47 locale tag to filter by (e.g. "en-US", "pt-BR").                                         |
| `seed`    | integer | No       | Controls which batch of results to return. `0` returns the top matches, `1` the next batch, etc. |

## Step 3: Use a Voice in Video Creation

Once you have a `voice_id`, pass it when creating a video.

### Example Request with Video Agent

```bash
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A 30-second explainer about cloud computing benefits", "voice_id": "1bd001e7e50f421d891986aad5c8bbd2"}'
```

### Example Request with Direct Video Creation

```bash
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "avatar", "avatar_id": "your_look_id", "voice_id": "1bd001e7e50f421d891986aad5c8bbd2", "script": "Welcome to our platform. Today I will walk you through the key features."}'
```

### Voice Settings

When using `POST /v3/videos`, you can fine-tune playback via `voice_settings`:

```json
{
  "type": "avatar",
  "avatar_id": "your_look_id",
  "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
  "script": "Welcome to our platform.",
  "voice_settings": {
    "speed": 1.1,
    "pitch": 0.0,
    "locale": "en-US"
  }
}
```

| Field   | Type   | Range          | Description                                                        |
|---------|--------|----------------|--------------------------------------------------------------------|
| `speed` | number | `0.5` – `1.5` | Playback speed multiplier. `1.0` is normal speed.                 |
| `pitch` | number | `-50` – `+50`  | Pitch adjustment in semitones.                                     |
| `locale`| string | BCP-47         | Locale/accent hint for multi-lingual voices.                      |