--- title: "GET /voices/library — Библиотека голосов" url: https://lumean.app/developers/docs/api/get-voices-library locale: ru description: "Библиотека голосов" generated: 2026-11-08 operationId: voice.library method: GET path: /voices/library scopes: [voices.read] spec_version: 1.0.0 --- # GET /voices/library **Библиотека голосов** Личная библиотека: **всё, чем вы можете озвучивать прямо сейчас** — собственные готовые голоса плюс добавленные из публичного каталога. Это самый практичный список для выбора `voice_id`: в отличие от `GET /voices`, сюда не попадают недоделанные и отклонённые голоса. У каждой записи есть ваше локальное прозвище (`nickname`) и признак доступности — фильтруется параметром `available`. **Требуемое право ключа:** `voices.read`. - Право ключа: `voices.read` ## Запрос ```bash curl -X GET 'https://api.lumean.app/api/public/voices/library' \ -H 'Accept: application/json' \ -H 'X-API-KEY: YOUR_API_KEY' ``` ## Параметры | Поле | Где | Тип | Обяз. | Описание | | --- | --- | --- | --- | --- | | `available` | query | `boolean` | — | Только голоса, доступные для генерации прямо сейчас (`true`), либо только недоступные (`false`). | | `search` | query | `string` | — | Поиск по вашему прозвищу голоса (`nickname`) и его исходному названию. | | `language_code` | query | `string` | — | Фильтр по языку, ISO-639-1 (`ru`, `en`, `de`, …). | | `sort_by` | query | `string` — `added_at` · `created_at` · `nickname` | — | Поле сортировки. По умолчанию `added_at`. | | `sort_order` | query | `string` — `asc` · `desc` | — | Направление сортировки. | | `page` | query | `integer` | — | Номер страницы, начиная с `1`. | | `per_page` | query | `integer` | — | Сколько записей вернуть на странице. Мета страницы — в `data` рядом со списком `items`: `current_page`, `last_page`, `per_page`, `total`. | | `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` | `UserLibraryList` | обяз. | Голоса, добавленные вами в личную библиотеку. | | `data.items` | `array` | обяз. | Записи текущей страницы в порядке сортировки списка. | | `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": 12, "voice_id": "k3nH9vRt2Lw7ZpXb", "nickname": null, "added_at": "2026-06-05T10:00:00+00:00", "available": true, "unavailable_reason": null, "origin": "own", "voice": { "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" } } }, { "id": 13, "voice_id": "Xh7Nc2Rt9BqZm4Wv", "nickname": "Ad voice backup", "added_at": "2026-05-25T14:00:00+00:00", "available": false, "unavailable_reason": "admin_force_removed", "origin": "library", "voice": { "id": "Xh7Nc2Rt9BqZm4Wv", "display_name": "Owen Commercial (EN)", "description": "Confident male voice tuned for commercial and advertisement reads.", "gender": "male", "accent": "uk", "default_language_code": "en", "voice_status": "ready", "publication_status": "rejected", "allow_usage_in_orders": false, "preview_generated_at": "2026-05-20T12:00:00+00:00", "created_at": "2026-05-18T09:00:00+00:00", "updated_at": "2026-07-10T11:00:00+00:00", "tags": [ { "id": 5, "code": "energetic", "name": "Energetic", "description": null, "color": null, "sort_order": 50 } ], "languages": [ { "id": 3, "language_code": "en", "status": "ready", "reference_duration_ms": 51000, "model_version": 1, "failure_reason": null, "clone_started_at": "2026-05-18T09:05:00+00:00", "clone_completed_at": "2026-05-18T09:25:00+00:00", "updated_at": "2026-05-18T09:25:00+00:00" } ], "preview_urls": { "en": "https://s3.lumean.app/lumean/storage/lumvoice/voices/Xh7Nc2Rt9BqZm4Wv/previews/en.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260520%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260520T120000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=7a1c9e3f5b2d4a86c0f7e9d1b3a5c8e2f4b6d0a2c4e6f8b1d3a5c7e9f0b2d4a6" } } } ], "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 **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. | | `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). | **Пример** ```json { "success": false, "message": "This API key does not have permission to perform this action." } ``` ### 422 — Ошибка валидации. Поля с ошибками перечислены в `errors`. **Поля ответа** | Поле | Тип | Обяз. | Описание | | --- | --- | --- | --- | | `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. | | `message` | `string` | обяз. | Сводка ошибок валидации словами, на языке ответа (`X-Locale`). | | `errors` | `object` | обяз. | Разбор по полям: ключ — поле запроса, значение — список претензий к нему. | | `errors.*` | `array` — произвольные ключи | — | | **Пример** ```json { "success": true, "message": "string", "errors": {} } ``` --- - Эта же страница в браузере: https://lumean.app/developers/docs/api/get-voices-library - Машинный справочник целиком: https://api.lumean.app/docs/llm.md