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

# GET /voices

**My Voices**

Голоса LumVoice, **созданные владельцем ключа**, в любом статусе — включая те, что ещё
клонируются или не прошли модерацию.

Для генерации годятся только голоса со `voice_status: ready`; идентификатор такого
голоса подставляется в `config.tts_settings.voice_id` шаблона или в `config_override`
заказа.

Публичный API — read-only: создать или изменить голос по ключу нельзя.

**Требуемое право ключа:** `voices.read`.

- Право ключа: `voices.read`

## Запрос

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

## Параметры

| Поле | Где | Тип | Обяз. | Описание |
| --- | --- | --- | --- | --- |
| `voice_status` | query | `string` — `pending_clone` · `cloning` · `ready` · `clone_failed` · `archived` | — | Стадия жизненного цикла клонированного голоса. Готов к использованию только `ready`. |
| `publication_status` | query | `string` — `private` · `pending_review` · `public` · `rejected` | — | Статус публикации голоса в общем каталоге. |
| `language_code` | query | `string` | — | Фильтр по языку, ISO-639-1 (`ru`, `en`, `de`, …). |
| `search` | query | `string` | — | Поиск по названию (`display_name`) и описанию голоса. |
| `sort_by` | query | `string` — `created_at` · `updated_at` · `display_name` · `last_used_at` · `usage_count_total` | — | Поле сортировки. По умолчанию `created_at`. |
| `sort_order` | query | `string` — `asc` · `desc` | — | Направление сортировки. |
| `per_page` | query | `integer` | — | Сколько записей вернуть на странице. Метаданные пагинации лежат рядом с `items`: `current_page`, `last_page`, `per_page`, `total`. |

## Тело запроса

Тела нет.

## Ответы

### 200 — Список голосов владельца ключа

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь `true`, а ошибка приходит телом другой формы, где этого поля может не быть вовсе. |
| `message` | `string` | обяз. | Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются. |
| `data` | `LumVoiceList` | обяз. | Ваши голоса LumVoice — и собственные, и добавленные в библиотеку. |
| `data.items` | `array<LumVoice>` | обяз. | Записи текущей страницы в порядке сортировки списка. |
| `data.items[].id` | `string` | обяз. | UUID голоса. Кладётся в `config.voice_id` шаблона; для путей `/voices/{voice}` — он же. |
| `data.items[].display_name` | `string` | обяз. | Название голоса для показа. |
| `data.items[].description` | `string` | обяз. | Описание голоса от автора: тембр, манера, сценарии использования. |
| `data.items[].gender` | `string` | обяз. | Пол голоса. |
| `data.items[].accent` | `string` | обяз. | Акцент или региональный вариант произношения. |
| `data.items[].default_language_code` | `string` | обяз. | Язык, на котором голос звучит по умолчанию, ISO-639-1. |
| `data.items[].voice_status` | `string` | обяз. | Состояние клонирования голоса. Использовать в заказах можно только полностью готовый. |
| `data.items[].publication_status` | `string` | обяз. | Стадия публикации: черновик, на модерации, опубликован. Определяет, виден ли голос в общем каталоге `GET /voices/public`. |
| `data.items[].allow_usage_in_orders` | `boolean` | обяз. | Разрешил ли автор использовать голос другим. Без этого флага голос не попадает в каталог `GET /voices/public`, а у тех, кто уже добавил его в свою библиотеку, запись становится недоступной. |
| `data.items[].preview_generated_at` | `string` — date-time — nullable | обяз. | Когда собраны демо-фрагменты, ISO 8601. `null` — превью ещё нет. |
| `data.items[].created_at` | `string` — date-time — nullable | обяз. | Когда голос создан, ISO 8601. |
| `data.items[].updated_at` | `string` — date-time — nullable | обяз. | Когда голос последний раз менялся, ISO 8601. |
| `data.items[].tags` | `array<VoiceTag>` | — | Метки голоса для поиска и фильтрации. Полный справочник — `GET /voices/tags`. |
| `data.items[].tags[].id` | `integer` | обяз. | Внутренний идентификатор метки. |
| `data.items[].tags[].code` | `string` | обяз. | Код метки — устойчивое значение для фильтрации, в отличие от переводимого `name`. |
| `data.items[].tags[].name` | `string` | обяз. | Название метки на языке аккаунта. |
| `data.items[].tags[].description` | `string` — nullable | обяз. | Пояснение к метке на языке аккаунта, если автор его задал. |
| `data.items[].tags[].color` | `string` | обяз. | Цвет метки в HEX — подсказка для оформления. |
| `data.items[].tags[].sort_order` | `integer` | обяз. | Вес сортировки в списке меток: меньше — выше. |
| `data.items[].languages` | `array<VoiceLanguage>` | — | Языки, на которые голос склонирован, с состоянием каждого клона. Заказ возможен только на готовом языке. |
| `data.items[].languages[].id` | `integer` | обяз. | Внутренний идентификатор языковой версии голоса. |
| `data.items[].languages[].language_code` | `string` | обяз. | Код языка, ISO-639-1. Он же — ключ в `preview_urls`. |
| `data.items[].languages[].status` | `string` | обяз. | Состояние клонирования для этого языка. Заказ принимается только на языке, где клон готов. |
| `data.items[].languages[].reference_duration_ms` | `integer` — nullable | обяз. | Длительность референсной записи в миллисекундах — на ней обучен клон. |
| `data.items[].languages[].model_version` | `integer` | обяз. | Версия обученной модели. Растёт при переобучении голоса. |
| `data.items[].languages[].failure_reason` | `string` — nullable | обяз. | Почему клонирование не удалось. `null`, если сбоя не было. |
| `data.items[].languages[].clone_started_at` | `string` — date-time — nullable | обяз. | Когда клонирование началось, ISO 8601. |
| `data.items[].languages[].clone_completed_at` | `string` — date-time — nullable | обяз. | Когда клонирование завершилось, ISO 8601. `null` — ещё идёт либо не удалось. |
| `data.items[].languages[].updated_at` | `string` — date-time — nullable | обяз. | Когда языковая версия последний раз менялась, ISO 8601. |
| `data.items[].preview_urls` | `object` | обяз. | Демо-фрагменты по языкам: ключ — код языка, значение — временная ссылка на аудио либо `null`, если превью для языка нет. Ссылки живут около минуты. |
| `data.items[].preview_urls.*` | `string` — произвольные ключи — nullable | — |  |
| `data.current_page` | `integer` | обяз. | Номер текущей страницы, с единицы. |
| `data.last_page` | `integer` | обяз. | Номер последней страницы. Обход списка закончен, когда `current_page` равен `last_page`. |
| `data.per_page` | `integer` | обяз. | Размер страницы, применённый сервером. |
| `data.total` | `integer` | обяз. | Сколько записей всего по фильтру. |

**Пример**

```json
{
  "success": true,
  "message": "Success",
  "data": {
    "items": [
      {
        "id": "Qm4Bx8Yt1WvNc6Zs",
        "display_name": "Marcus Draft (EN)",
        "description": null,
        "gender": "male",
        "accent": null,
        "default_language_code": null,
        "voice_status": "cloning",
        "publication_status": "private",
        "allow_usage_in_orders": true,
        "preview_generated_at": null,
        "created_at": "2026-07-16T18:00:00+00:00",
        "updated_at": "2026-07-17T08:30:00+00:00",
        "tags": [],
        "languages": [
          {
            "id": 2,
            "language_code": "en",
            "status": "cloning",
            "reference_duration_ms": 32000,
            "model_version": 1,
            "failure_reason": null,
            "clone_started_at": "2026-07-17T08:30:00+00:00",
            "clone_completed_at": null,
            "updated_at": "2026-07-17T08:30:00+00:00"
          }
        ],
        "preview_urls": {
          "en": null
        }
      },
      {
        "id": "k3nH9vRt2Lw7ZpXb",
        "display_name": "Ava Narrator (EN)",
        "description": "Warm, measured narration voice cloned from a 45-second studio reference — ideal for long-form audiobook and e-learning narration.",
        "gender": "female",
        "accent": "us",
        "default_language_code": "en",
        "voice_status": "ready",
        "publication_status": "public",
        "allow_usage_in_orders": true,
        "preview_generated_at": "2026-06-02T09:15:00+00:00",
        "created_at": "2026-06-01T10:00:00+00:00",
        "updated_at": "2026-06-02T09:15:00+00:00",
        "tags": [
          {
            "id": 8,
            "code": "narration",
            "name": "Narration",
            "description": null,
            "color": null,
            "sort_order": 80
          },
          {
            "id": 4,
            "code": "calm",
            "name": "Calm",
            "description": null,
            "color": null,
            "sort_order": 40
          }
        ],
        "languages": [
          {
            "id": 1,
            "language_code": "en",
            "status": "ready",
            "reference_duration_ms": 47000,
            "model_version": 1,
            "failure_reason": null,
            "clone_started_at": "2026-06-01T10:05:00+00:00",
            "clone_completed_at": "2026-06-01T10:22:00+00:00",
            "updated_at": "2026-06-01T10:22:00+00:00"
          }
        ],
        "preview_urls": {
          "en": "https://s3.lumean.app/lumean/storage/lumvoice/voices/k3nH9vRt2Lw7ZpXb/previews/en.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260602%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260602T091500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=3f9c2b0a1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a"
        }
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 2
  }
}
```

### 401 — Невалидный или отсутствующий X-API-KEY

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `data` | `null` — nullable | обяз. | Всегда `null`, когда запрос отклонён до обработки. |

**Пример**

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

### 403 — У ключа нет права voices.read

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Error overview. |

**Пример**

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

### 422 — Ошибка валидации. Поля с ошибками перечислены в `errors`.

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Errors overview. |
| `errors` | `object` | обяз. | A detailed description of each field that failed validation. |
| `errors.*` | `array<string>` — произвольные ключи | — |  |

**Пример**

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

---

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