---
title: "Голоса"
url: https://lumean.app/developers/docs/guide/voices
locale: ru
description: "Каталоги голосов LumVoice, ElevenLabs, HeyGen, Cartesia и Fish Audio. Где найти voice_id и как передать его в шаблон."
updated: 2026-10-18
sources: [get-voices, get-voices-voice, get-voices-library, get-voices-public, get-voices-tags, get-voices-elevenlabs-library, get-voices-heygen, get-voices-heygen-filters, get-voices-cartesia, get-voices-cartesia-clones, get-voices-fishaudio, get-voices-fishaudio-clones]
errors: ["403", "404"]
spec_version: 1.0.0
---

# Голоса

Голоса берутся из собственного каталога LumVoice и из каталогов поставщиков: ElevenLabs,
HeyGen, Cartesia и Fish Audio. Схема элемента, значения `gender` и пагинация у каталогов
разные. Общее у них — право `voices.read` и результат: идентификатор голоса, который кладётся в
шаблон.

Каталоги доступны только для чтения: голос LumVoice по ключу не создаётся. Клон голоса по
ключу можно создать у Cartesia и Fish Audio: `POST /voices/cartesia/clones` и
`POST /voices/fishaudio/clones`, право `voices.write`.

## Каталоги

| Каталог | Операции | Что идёт в шаблон |
| --- | --- | --- |
| LumVoice — голоса платформы | `GET /voices`, `/voices/library`, `/voices/public`, `/voices/tags`, `/voices/{voice}` | `id` элемента |
| ElevenLabs — публичная Voice Library, объекты поставщика без изменений | `GET /voices/elevenlabs/library` | `voice_id`, шаблон `elevenlabs` |
| HeyGen — каталог поставщика со своим набором фильтров | `GET /voices/heygen`, `/voices/heygen/filters` | `voice_id`, шаблон `heygen` |
| Cartesia | `GET /voices/cartesia`; свои клоны — `GET /voices/cartesia/clones` | `voice_id`, шаблон `cartesia` |
| Fish Audio | `GET /voices/fishaudio`; свои клоны — `GET /voices/fishaudio/clones` | `voice_id`, шаблон `fishaudio` |

Списки LumVoice решают разные задачи:

| Операция | Что возвращает |
| --- | --- |
| `GET /voices` | Ваши голоса в любом состоянии, включая недоклонированные и отклонённые модерацией |
| `GET /voices/library` | Голоса, которыми можно озвучивать сейчас: свои готовые и добавленные из каталога. У записи есть прозвище `nickname` и признак `available` |
| `GET /voices/public` | Общий каталог. В него попадают только голоса, пригодные для заказа |

Для выбора голоса под заказ `GET /voices` подходит хуже других списков: в нём есть голоса,
которыми озвучивать нельзя.

Cartesia и Fish Audio доступны не всем. Если сервис закрыт для владельца ключа, каталог
отвечает `404` с `reason: service_not_found`.

## Пагинация каталогов

| Каталоги | Обёртка в `data` | Первая страница | Размер страницы |
| --- | --- | --- | --- |
| LumVoice | `items`, `current_page`, `last_page`, `per_page`, `total` | `page=1` | `per_page` 1–100, по умолчанию 20 |
| Cartesia, Fish Audio | `items`, `current_page`, `last_page`, `per_page`, `total` | `page=1` | `per_page` 1–200, по умолчанию 50 |
| ElevenLabs, HeyGen | `voices`, `total`, `page`, `page_size`, `has_more` | `page=0` | `page_size`: ElevenLabs до 50 (по умолчанию 30), HeyGen до 200 (по умолчанию 55) |

У ElevenLabs и HeyGen выходите из цикла по `has_more`. Подробнее — в руководстве
[Пагинация](/developers/docs/guide/pagination).

## Значения `gender`

| Каталог | Значения |
| --- | --- |
| `GET /voices/public` (LumVoice) | `male`, `female`, `neutral` |
| `GET /voices/elevenlabs/library` | `male`, `female` |
| `GET /voices/heygen` | `male`, `female`, `unknown` |
| `GET /voices/cartesia` | `masculine`, `feminine`, `gender_neutral` |
| `GET /voices/fishaudio` | `male`, `female` |

Общего фильтра по полу для всех каталогов нет, поэтому значения приводят к своим на клиенте.
У Cartesia и Fish Audio `gender` в ответе может быть `null`.

У ElevenLabs фильтр `age` принимает `young`, `middle_aged` и `old`, через нижнее
подчёркивание. Сервер не сверяет значение со списком и передаёт его ElevenLabs как есть,
поэтому опечатку вроде `middle-aged` он не отклонит с `422`.

## Проверка голоса LumVoice перед заказом

| Откуда голос | Что проверять |
| --- | --- |
| `GET /voices/public` | Ничего: каталог отфильтрован по `voice_status` и `allow_usage_in_orders` |
| `GET /voices/library` | `available`. При `false` причина — в `unavailable_reason` |
| `GET /voices` (свои) | `languages[]`: заказ возможен на языке, клон которого завершён |

Статусы голоса: `pending_clone`, `cloning`, `ready`, `partially_ready`, `clone_failed`,
`archived`. `ready` — голос готов целиком. `partially_ready` — часть языков склонирована, часть
нет, и рабочие языки доступны. Для такого голоса решает состояние языка в `languages[]`, а не
общий статус: поле `status`, причина сбоя — в `failure_reason`.

Фильтр `voice_status` у `GET /voices` принимает любое из этих шести значений. Неизвестное
значение сервер пропускает без ошибки и возвращает список без фильтра.

`publication_status` и `allow_usage_in_orders` управляют видимостью в каталоге, а не допуском к
заказу. На ваши собственные голоса `allow_usage_in_orders` не влияет. Когда голос пропадает из
каталога, у пользователей, которые уже добавили его в библиотеку, запись получает
`available: false`. Причину называет `unavailable_reason`: `author_unpublished`,
`admin_force_removed`, `author_deleted` или `owner_deleted`.

### GET /voices/public

Публичный каталог голосов

Справочник: https://lumean.app/developers/docs/api/get-voices-public

## Движки HeyGen

`GET /templates/config-options?service=heygen` перечисляет движки, которые поддерживает сервис.
Движки конкретного голоса — в поле `voice_engines` элемента каталога. Нужен движок, который
есть в обоих списках: из 2330 голосов 1947 поддерживают `elevenLabs`, а 383 не поддерживают ни
одного из перечисленных. Несовместимую пару «голос и движок» сервер отклоняет с `422`. Ошибка
приходит в поле `config.tts_settings.voice_id`, а не в поле движка.

Значения `language`, `accent` и `voice_engine` пишутся так же, как у HeyGen: `English`,
`en-US`. Список значений со счётчиками возвращает `GET /voices/heygen/filters`. Вызывайте его
перед поиском.

## Cartesia и Fish Audio

- В шаблон идёт `voice_id`, а не `id`. Элемент каталога содержит оба поля. `id` — внутренний
  номер записи, для озвучки он не нужен.
- Параметр `voice_id` находит один голос по точному идентификатору. Так удобно подписать голос,
  уже выбранный в шаблоне, без перебора страниц. Голос, снятый с каталога, вернёт пустой список.
- Свой клон в каталоге не появляется. Его `voice_id` возвращают `GET /voices/cartesia/clones`
  и `GET /voices/fishaudio/clones`, и только у клона в статусе `ready`. Пока клон в статусе
  `pending` или `cloning`, `voice_id` равен `null`.
- Cartesia принимает и голос, склонированный вне Lumean, например на cartesia.ai. Его UUID
  кладётся в `tts_settings.voice_id` как есть.
- `voice_id` у Fish Audio — 32 hex-символа, а не UUID. Фильтр языка у Fish Audio принимает
  только `ru`, `en` и `es`. Ёмкость фрагмента у Fish Audio считается в байтах UTF-8, а не в
  символах (`capacity_unit`, см. руководство [Текст озвучки](/developers/docs/guide/text)).

### `get-voices-cartesia`

Справочник: https://lumean.app/developers/docs/api/get-voices-cartesia

## Голос в шаблоне

```json
{
  "service_key": "elevenlabs",
  "name": "Narrator EN",
  "config": { "tts_settings": { "mode": "mode_v1", "model_id": "eleven_multilingual_v2", "voice_id": "<VOICE_ID>", "voice_settings": { "stability": 0.5 } } }
}
```

Идентификатор голоса кладётся в шаблон того же сервиса, в `config.tts_settings.voice_id`. У
заказа поля `voice_id` нет. Откуда брать значение и какой `service_key` указать, показывает
таблица в разделе «Каталоги».

Чтобы один раз заменить голос без нового шаблона, передайте `config_override` в заказе. Как
собрать конфиг, описано в руководстве [Шаблоны](/developers/docs/guide/templates).

## Особенности ответов

- `preview_urls` у LumVoice действуют около минуты. Это карта «код языка → подписанная ссылка
  или `null`», надолго её не кэшируйте. У каталогов поставщиков вместо неё поле `preview_url`.
  У Fish Audio это временная ссылка на 60 минут, а до скачивания превью — `null`.
- Названия тегов локализованы: `name` приходит на языке запроса, см.
  [Ключ, права и заголовки](/developers/docs/guide/authentication). Фильтруйте по `tag_ids[]`,
  а сравнивайте теги по `code`.
- Идентификатор LumVoice — случайная строка из 16 символов, например `k3nH9vRt2Lw7ZpXb`, а не
  UUID. Не проверяйте его на клиенте как UUID.
- Каталог ElevenLabs зависит от внешнего API и при его недоступности отвечает `503`.
- `GET /voices/{voice}` возвращает `403` на чужой непубличный голос и `404` на несуществующий.

### `get-voices-elevenlabs-library`

Справочник: https://lumean.app/developers/docs/api/get-voices-elevenlabs-library

---

- Эта же страница в браузере: https://lumean.app/developers/docs/guide/voices
- Машинный справочник целиком: https://api.lumean.app/docs/llm.md