GET/voices

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

voices.read

Поправки к спецификации · 1

Пагинация лежит не в data.meta
Четыре описания параметра per_page обещают метаданные пагинации в data.meta. Такого ключа нет ни в одном ответе публичного API: страница приходит плоско — data.items[] плюс data.current_page, data.last_page, data.per_page, data.total. Код, читающий data.meta.total, получит undefined.

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

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

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

На этой странице(3)

Параметры

Поля ввода живут прямо в строке запроса: подставьте значение — и получите готовый URL. Ниже — тип, обязательность и допустимые значения каждого параметра.

GEThttps://api.lumean.app/api/public/voices

voice_statusstringв queryнеобязательный
Стадия жизненного цикла клонированного голоса. Готов к использованию только ready.
Допустимые значения
publication_statusstringв queryнеобязательный
Статус публикации голоса в общем каталоге.
Допустимые значения
language_codestringв queryнеобязательный
Фильтр по языку, ISO-639-1 (ru, en, de, …).
searchstringв queryнеобязательный
Поиск по названию (display_name) и описанию голоса.
sort_bystringв queryнеобязательный
Поле сортировки. По умолчанию created_at.
Допустимые значения
sort_orderstringв queryнеобязательный
Направление сортировки.
Допустимые значения
per_pageintegerв queryнеобязательный
Сколько записей вернуть на странице. Метаданные пагинации лежат рядом с items: current_page, last_page, per_page, total.

Возможные ответы

200

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

Пример тела

{
  "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
  }
}

Поля ответа

successобязательное

Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь true, а ошибка приходит телом другой формы, где этого поля может не быть вовсе.

boolean

messageобязательное

Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются.

string

dataобязательное

Ваши голоса LumVoice — и собственные, и добавленные в библиотеку.

LumVoiceListLumVoiceList

itemsобязательное

Записи текущей страницы в порядке сортировки списка.

array<LumVoice>LumVoice

элемент массива

idобязательное

UUID голоса. Кладётся в config.voice_id шаблона; для путей /voices/{voice} — он же.

string

display_nameобязательное

Название голоса для показа.

string

descriptionобязательное

Описание голоса от автора: тембр, манера, сценарии использования.

string

genderобязательное

Пол голоса.

string

accentобязательное

Акцент или региональный вариант произношения.

string

default_language_codeобязательное

Язык, на котором голос звучит по умолчанию, ISO-639-1.

string

voice_statusобязательное

Состояние клонирования голоса. Использовать в заказах можно только полностью готовый.

string

publication_statusобязательное

Стадия публикации: черновик, на модерации, опубликован. Определяет, виден ли голос в общем каталоге GET /voices/public.

string

allow_usage_in_ordersобязательное

Разрешил ли автор использовать голос другим. Без этого флага голос не попадает в каталог GET /voices/public, а у тех, кто уже добавил его в свою библиотеку, запись становится недоступной.

boolean

preview_generated_atобязательное

Когда собраны демо-фрагменты, ISO 8601. null — превью ещё нет.

может быть nulldate-time

string

created_atобязательное

Когда голос создан, ISO 8601.

может быть nulldate-time

string

updated_atобязательное

Когда голос последний раз менялся, ISO 8601.

может быть nulldate-time

string

tagsнеобязательное

Метки голоса для поиска и фильтрации. Полный справочник — GET /voices/tags.

array<VoiceTag>VoiceTag

элемент массива

idобязательное

Внутренний идентификатор метки.

integer

codeобязательное

Код метки — устойчивое значение для фильтрации, в отличие от переводимого name.

string

nameобязательное

Название метки на языке аккаунта.

string

descriptionобязательное

Пояснение к метке на языке аккаунта, если автор его задал.

может быть null

string

colorобязательное

Цвет метки в HEX — подсказка для оформления.

string

sort_orderобязательное

Вес сортировки в списке меток: меньше — выше.

integer

languagesнеобязательное

Языки, на которые голос склонирован, с состоянием каждого клона. Заказ возможен только на готовом языке.

array<VoiceLanguage>VoiceLanguage

элемент массива

idобязательное

Внутренний идентификатор языковой версии голоса.

integer

language_codeобязательное

Код языка, ISO-639-1. Он же — ключ в preview_urls.

string

statusобязательное

Состояние клонирования для этого языка. Заказ принимается только на языке, где клон готов.

string

reference_duration_msобязательное

Длительность референсной записи в миллисекундах — на ней обучен клон.

может быть null

integer

model_versionобязательное

Версия обученной модели. Растёт при переобучении голоса.

integer

failure_reasonобязательное

Почему клонирование не удалось. null, если сбоя не было.

может быть null

string

clone_started_atобязательное

Когда клонирование началось, ISO 8601.

может быть nulldate-time

string

clone_completed_atобязательное

Когда клонирование завершилось, ISO 8601. null — ещё идёт либо не удалось.

может быть nulldate-time

string

updated_atобязательное

Когда языковая версия последний раз менялась, ISO 8601.

может быть nulldate-time

string

preview_urlsобязательное

Демо-фрагменты по языкам: ключ — код языка, значение — временная ссылка на аудио либо null, если превью для языка нет. Ссылки живут около минуты.

object

*необязательное

может быть nullпроизвольные ключи

string

current_pageобязательное

Номер текущей страницы, с единицы.

integer

last_pageобязательное

Номер последней страницы. Обход списка закончен, когда current_page равен last_page.

integer

per_pageобязательное

Размер страницы, применённый сервером.

integer

totalобязательное

Сколько записей всего по фильтру.

integer

401

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

Разобрать этот ответ

Пример тела

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

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

dataобязательное

Всегда null, когда запрос отклонён до обработки.

может быть null

null

403

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

Разобрать этот ответ

Пример тела

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

Поля ответа

messageобязательное

Error overview.

string

422

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

Разобрать этот ответ

Пример тела

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

Поля ответа

messageобязательное

Errors overview.

string

errorsобязательное

A detailed description of each field that failed validation.

object

*необязательное

произвольные ключи

array<string>

Об этом словами

Объекты

Соседние операции

Ещё

Скормить страницу ИИ

Открыть .md llm.md

спека 0.0.1

Параметры

Возможные ответы

Рядом

Скормить страницу ИИ