---
title: "GET /voices/{voice} — Голос"
url: https://lumean.app/developers/docs/api/get-voices-voice
locale: ru
description: "Голос"
generated: 2026-11-08
operationId: voice.show
method: GET
path: "/voices/{voice}"
scopes: [voices.read]
spec_version: 1.0.0
---

# GET /voices/{voice}

**Голос**

Карточка одного голоса: язык, пол, теги, статус и превью.

Голос виден, если он ваш, опубликован в общем каталоге либо добавлен в вашу библиотеку.
Чужой непубличный голос — `403`.

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

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

## Запрос

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

## Параметры

| Поле | Где | Тип | Обяз. | Описание |
| --- | --- | --- | --- | --- |
| `voice` | path | `string` | обяз. | Идентификатор голоса — строка из 16 латинских букв и цифр, не UUID и не число. Берётся из поля `id` в `GET /voices` (ваши голоса) или `GET /voices/public` (общий каталог). Это НЕ `voice_id` внешних провайдеров: у ElevenLabs и HeyGen идентификаторы своего формата, и здесь они не подойдут. |
| `X-Locale` | header | `string` | — | Язык локализованных текстов ответа (`message`, подписи, причины ошибок), код ISO-639-1. Необязателен; без него — язык аккаунта владельца ключа, затем `Accept-Language`, затем язык по умолчанию. Неизвестный или неподдерживаемый код пропускается так же, как отсутствующий. |
| `X-Timezone` | header | `string` | — | IANA-зона (`Europe/Moscow`), в которой ответ показывает моменты времени — ISO-8601 со смещением. Необязателен; без него даты приходят в UTC. Невалидная зона игнорируется. Применённую зону сервер возвращает в одноимённом заголовке ответа. |

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

Тела нет.

## Ответы

### 200 — Детали голоса

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

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

**Пример**

```json
{
  "success": true,
  "message": "Success",
  "data": {
    "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"
    }
  }
}
```

### 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."
}
```

### 404 — Голос не найден

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `reason` | `string` | — | Машиночитаемая причина — приходит у бизнес-отказов (например, `invalid_order_status`); у прочих ошибок поля нет. Ветвите обработку по нему, а не по тексту сообщения. |
| `error_code` | `string` | — | Тот же машинный код, что в `reason`, — второе имя поля. Приходит вместе с `reason`, значения всегда совпадают. |

**Пример**

```json
{
  "success": false,
  "message": "Resource not found."
}
```

---

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