--- title: "GET /voices/library — Voice Library" url: https://lumean.app/en/developers/docs/api/get-voices-library locale: en description: "Voice Library" generated: 2026-10-17 operationId: voice.library method: GET path: /voices/library scopes: [voices.read] spec_version: 0.0.1 --- # GET /voices/library **Voice Library** Your personal library — **everything you can narrate with right now**: your own finished voices plus the ones you added from the public catalogue. This is the practical list for picking a `voice_id`: unlike `GET /voices`, it never contains unfinished or rejected voices. Each entry has your local nickname (`nickname`) and an availability flag, filterable through `available`. **Required key permission:** `voices.read`. - Required scope: `voices.read` ## Request ```bash curl -X GET 'https://api.lumean.app/api/public/voices/library' \ -H 'Accept: application/json' \ -H 'X-API-KEY: YOUR_API_KEY' ``` ## Parameters | Field | In | Type | Req. | Description | | --- | --- | --- | --- | --- | | `available` | query | `boolean` | — | Only voices usable for generation right now (`true`), or only unusable ones (`false`). | | `search` | query | `string` | — | Search by your nickname for the voice and by its original name. | | `language_code` | query | `string` | — | Language filter, ISO-639-1 (`ru`, `en`, `de`, …). | | `sort_by` | query | `string` — `added_at` · `created_at` · `nickname` | — | Sort field. Defaults to `added_at`. | | `sort_order` | query | `string` — `asc` · `desc` | — | Sort direction. | | `per_page` | query | `integer` | — | How many records to return per page. Pagination metadata sits next to `items`: `current_page`, `last_page`, `per_page`, `total`. | ## Request body No body. ## Responses ### 200 — Success. The payload is in `data`. **Response fields** | Field | Type | Req. | Description | | --- | --- | --- | --- | | `success` | `boolean` | required | Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all. | | `message` | `string` | required | A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code. | | `data` | `UserLibraryList` | required | Voices you have added to your personal library. | | `data.items` | `array` | required | Records on the current page, in the list’s sort order. | | `data.current_page` | `integer` | required | Current page number, starting from one. | | `data.last_page` | `integer` | required | Number of the last page. The walk is over once `current_page` equals `last_page`. | | `data.per_page` | `integer` | required | Page size the server applied. | | `data.total` | `integer` | required | Total number of records matching the filter. | **Example** ```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 — The key is missing, unknown, disabled or expired. **Response fields** | Field | Type | Req. | Description | | --- | --- | --- | --- | | `success` | `boolean` | required | Always `false` in error responses. | | `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). | | `data` | `null` — nullable | required | Always `null` when the request is rejected before processing. | **Example** ```json { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } ``` ### 403 — The key lacks the required permission, or the object belongs to another user. **Response fields** | Field | Type | Req. | Description | | --- | --- | --- | --- | | `success` | `boolean` | required | Always `false` in error responses. | | `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). | **Example** ```json { "success": false, "message": "This API key does not have permission to perform this action." } ``` ### 422 — Validation error. Offending fields are listed in `errors`. **Response fields** | Field | Type | Req. | Description | | --- | --- | --- | --- | | `message` | `string` | required | Errors overview. | | `errors` | `object` | required | A detailed description of each field that failed validation. | | `errors.*` | `array` — arbitrary keys | — | | **Example** ```json { "message": "string", "errors": {} } ``` --- - This page in the browser: https://lumean.app/en/developers/docs/api/get-voices-library - Full machine-readable reference: https://api.lumean.app/docs/llm.md