---
title: "GET /voices/heygen — HeyGen Voices"
url: https://lumean.app/es/developers/docs/api/get-voices-heygen
locale: es
description: "HeyGen Voices"
generated: 2026-10-17
operationId: externalVoice.heygen
method: GET
path: /voices/heygen
scopes: [voices.read]
spec_version: 0.0.1
---

# GET /voices/heygen

**HeyGen Voices**

The HeyGen voice catalogue with filters by language, accent, gender and render engine.

Fetch the accepted filter values from `GET /voices/heygen/filters` first — the
spelling there is the provider's (`English`, `en-US`). Pages are numbered **from zero**.

**Required key permission:** `voices.read`.

- Permiso requerido: `voices.read`

## Petición

```bash
curl -X GET 'https://api.lumean.app/api/public/voices/heygen' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

## Parámetros

| Campo | En | Tipo | Oblig. | Descripción |
| --- | --- | --- | --- | --- |
| `gender` | query | `string` — `male` · `female` · `unknown` — ≤ 32 caracteres | — | Voice gender. |
| `language` | query | `string` — ≤ 64 caracteres | — | Voice language in HeyGen spelling (`English`, `Spanish`, …). Listed by `GET /voices/heygen/filters`. |
| `accent` | query | `string` — ≤ 16 caracteres | — | Region/accent (`en-US`, `en-GB`, …). Listed by `GET /voices/heygen/filters`. |
| `voice_engine` | query | `string` — ≤ 512 caracteres | — | Render engine; several values comma-separated. Listed by `GET /voices/heygen/filters`. |
| `search` | query | `string` — ≤ 128 caracteres | — | Search by voice name and internal `voice_name`. |
| `sort` | query | `string` — `default` · `name` · `newest` | — | Ordering. Defaults to `default`. |
| `page` | query | `integer` — ≥ 0 | — | Page number. Numbered **from zero**. |
| `page_size` | query | `integer` — 1..200 | — | Page size. Defaults to 55. |

## Cuerpo de la petición

Sin cuerpo.

## Respuestas

### 200 — Success. The payload is in `data`.

**Campos de la respuesta**

| Campo | Tipo | Oblig. | Descripción |
| --- | --- | --- | --- |
| `success` | `boolean` | obligatorio | Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all. |
| `message` | `string` | obligatorio | A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code. |
| `data` | `object` | obligatorio | The response payload. |
| `data.voices` | `array<object>` | obligatorio | Voices from the HeyGen catalogue. |
| `data.voices[].voice_id` | `string` | obligatorio | Voice identifier — goes into a heygen template’s `config.voice_id`. |
| `data.voices[].voice_name` | `string` | obligatorio | The provider’s original name for the voice. |
| `data.voices[].display_name` | `string` | obligatorio | Display name of the voice. |
| `data.voices[].gender` | `string` | obligatorio | Voice gender. Usable as a value for the `gender` filter. |
| `data.voices[].language` | `string` | obligatorio | Language in the provider’s spelling (`English`, `Spanish`). This is exactly what the `language` filter accepts — take it from here or from `/voices/heygen/filters` instead of guessing. |
| `data.voices[].locale` | `string` | obligatorio | Voice locale, when the provider supplies one. |
| `data.voices[].accent` | `string` | obligatorio | Accent in the provider’s spelling (`en-US`). The value for the `accent` filter. |
| `data.voices[].flag_url` | `string` | obligatorio | Link to the language flag icon — for decorating a list. |
| `data.voices[].preview_url` | `string` | obligatorio | Preview clip of the voice. The link points at our server, not the provider. |
| `data.voices[].voice_engines` | `array<string>` | obligatorio | Rendering engines available for this voice. The values work as `voice_engine` filter input. |
| `data.voices[].labels` | `array<string>` | obligatorio | Provider-supplied labels: delivery, use case, emotion. |
| `data.voices[].support_realtime` | `boolean` | obligatorio | Whether the voice supports the provider’s streaming mode. |
| `data.voices[].emotion_support` | `boolean` | obligatorio | Whether the voice accepts emotion directives. |
| `data.voices[].support_locale` | `boolean` | obligatorio | Whether a locale can be set for the voice independently of the language. |
| `data.total` | `integer` | obligatorio | How many voices match the filters, across all pages. |
| `data.page` | `integer` | obligatorio | Page number, zero-based. |
| `data.page_size` | `integer` | obligatorio | Page size the server applied. |
| `data.has_more` | `boolean` | obligatorio | Whether another page exists. |

**Ejemplo**

```json
{
  "success": true,
  "message": "HeyGen voices retrieved successfully.",
  "data": {
    "voices": [
      {
        "voice_id": "7f3a9c1e2b8d4f56a0c3e7f91b2d5a68",
        "voice_name": "Yb56nzJ2XkQ0Fh1PmT8L",
        "display_name": "Cassidy Pro",
        "gender": "female",
        "language": "English",
        "locale": null,
        "accent": "en-US",
        "flag_url": "https://resource2.heygen.ai/flags/us.png",
        "preview_url": "https://api.lumean.app/api/voice-preview?u=eyJpdiI6IjZmM2E5YzFlMmI4ZDRmNTYiLCJ2YWx1ZSI6ImZha2UifQ%3D%3D&signature=9f8e7d6c5b4a3928170f6e5d4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3a2918",
        "voice_engines": [
          "elevenLabs"
        ],
        "labels": [
          "Conversational",
          "Warm"
        ],
        "support_realtime": true,
        "emotion_support": false,
        "support_locale": false
      },
      {
        "voice_id": "c159d4a2f6b7483d95e0a1c8f4b2d637",
        "voice_name": "Xt4Wq8LmZ2VbPc6RfShu",
        "display_name": "Marcus Energetic",
        "gender": "male",
        "language": "English",
        "locale": null,
        "accent": "en-GB",
        "flag_url": "https://resource2.heygen.ai/flags/gb.png",
        "preview_url": "https://api.lumean.app/api/voice-preview?u=eyJpdiI6ImMxNTlkNGEyZjZiNzQ4M2QiLCJ2YWx1ZSI6ImZha2UifQ%3D%3D&signature=1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
        "voice_engines": [
          "elevenLabs",
          "azure"
        ],
        "labels": [
          "Energetic"
        ],
        "support_realtime": false,
        "emotion_support": true,
        "support_locale": true
      }
    ],
    "total": 2,
    "page": 0,
    "page_size": 55,
    "has_more": false
  }
}
```

### 401 — The key is missing, unknown, disabled or expired.

**Campos de la respuesta**

| Campo | Tipo | Oblig. | Descripción |
| --- | --- | --- | --- |
| `success` | `boolean` | obligatorio | Always `false` in error responses. |
| `message` | `string` | obligatorio | Error text in the key's language (set through the `X-Locale` header). |
| `data` | `null` — nullable | obligatorio | Always `null` when the request is rejected before processing. |

**Ejemplo**

```json
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
```

### 403 — The key lacks the required permission, or the object belongs to another user.

**Campos de la respuesta**

| Campo | Tipo | Oblig. | Descripción |
| --- | --- | --- | --- |
| `success` | `boolean` | obligatorio | Always `false` in error responses. |
| `message` | `string` | obligatorio | Error text in the key's language (set through the `X-Locale` header). |

**Ejemplo**

```json
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
```

### 422 — Validation error. Offending fields are listed in `errors`.

**Campos de la respuesta**

| Campo | Tipo | Oblig. | Descripción |
| --- | --- | --- | --- |
| `message` | `string` | obligatorio | Errors overview. |
| `errors` | `object` | obligatorio | A detailed description of each field that failed validation. |
| `errors.*` | `array<string>` — claves arbitrarias | — |  |

**Ejemplo**

```json
{
  "message": "string",
  "errors": {}
}
```

---

- Esta página en el navegador: https://lumean.app/es/developers/docs/api/get-voices-heygen
- Referencia completa legible por máquina: https://api.lumean.app/docs/llm.md