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

# GET /voices/public

**Public Voices Catalog**

The shared LumVoice catalogue available to everyone: only published (`public`), ready
(`ready`) and order-enabled voices appear here.

This is where you find a voice that is not yet in your library. Filters: tags
(`tag_ids[]`, listed by `GET /voices/tags`), language, gender and a search string.

**Required key permission:** `voices.read`.

- Gerekli izin: `voices.read`

## İstek

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

## Parametreler

| Alan | Yer | Tür | Zor. | Açıklama |
| --- | --- | --- | --- | --- |
| `tag_ids[]` | query | `array<integer>` | — | Tag filter, repeatable: `?tag_ids[]=3&tag_ids[]=7`. Tags are listed by `GET /voices/tags`. |
| `language_code` | query | `string` | — | Language filter, ISO-639-1 (`ru`, `en`, `de`, …). |
| `gender` | query | `string` — `male` · `female` · `neutral` | — | Voice gender. |
| `search` | query | `string` | — | Substring to search for. Case-insensitive. |
| `sort` | query | `string` — `popular` · `newest` · `name` | — | Catalogue ordering. Defaults to `popular`. |
| `per_page` | query | `integer` | — | How many records to return per page. Pagination metadata sits next to `items`: `current_page`, `last_page`, `per_page`, `total`. |

## İstek gövdesi

Gövde yok.

## Yanıtlar

### 200 — Success. The payload is in `data`.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | 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` | zorunlu | 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` | `PublicVoiceList` | zorunlu | The shared catalogue of published voices. You do not need to add a voice to your library to use it in orders. |
| `data.items` | `array<LumVoice>` | zorunlu | Records on the current page, in the list’s sort order. |
| `data.items[].id` | `string` | zorunlu | Voice UUID. Put it into a template’s `config.voice_id`; the same value goes into `/voices/{voice}` paths. |
| `data.items[].display_name` | `string` | zorunlu | Display name of the voice. |
| `data.items[].description` | `string` | zorunlu | Author’s description of the voice: timbre, delivery, intended use. |
| `data.items[].gender` | `string` | zorunlu | Voice gender. |
| `data.items[].accent` | `string` | zorunlu | Accent or regional pronunciation variant. |
| `data.items[].default_language_code` | `string` | zorunlu | The language the voice defaults to, ISO-639-1. |
| `data.items[].voice_status` | `string` | zorunlu | Cloning state of the voice. Only a fully prepared voice can be used in orders. |
| `data.items[].publication_status` | `string` | zorunlu | Publication stage: draft, under review, published. It determines whether the voice appears in the shared catalogue `GET /voices/public`. |
| `data.items[].allow_usage_in_orders` | `boolean` | zorunlu | Whether the author lets others use the voice. Without this flag the voice is absent from the `GET /voices/public` catalogue, and library entries other users already made for it become unavailable. |
| `data.items[].preview_generated_at` | `string` — date-time — nullable | zorunlu | When the preview clips were produced, ISO 8601. `null` means there is no preview yet. |
| `data.items[].created_at` | `string` — date-time — nullable | zorunlu | When the voice was created, ISO 8601. |
| `data.items[].updated_at` | `string` — date-time — nullable | zorunlu | When the voice last changed, ISO 8601. |
| `data.items[].tags` | `array<VoiceTag>` | — | Voice tags for search and filtering. The full directory is `GET /voices/tags`. |
| `data.items[].tags[].id` | `integer` | zorunlu | Internal identifier of the tag. |
| `data.items[].tags[].code` | `string` | zorunlu | Tag code — the stable value to filter by, unlike the translatable `name`. |
| `data.items[].tags[].name` | `string` | zorunlu | Tag name in the account language. |
| `data.items[].tags[].description` | `string` — nullable | zorunlu | Explanation of the tag in the account language, when the author provided one. |
| `data.items[].tags[].color` | `string` | zorunlu | Tag colour in HEX — a styling hint. |
| `data.items[].tags[].sort_order` | `integer` | zorunlu | Sort weight within the tag list: lower comes first. |
| `data.items[].languages` | `array<VoiceLanguage>` | — | Languages the voice has been cloned into, each with its own state. An order is only possible in a language that is ready. |
| `data.items[].languages[].id` | `integer` | zorunlu | Internal identifier of the voice’s language version. |
| `data.items[].languages[].language_code` | `string` | zorunlu | Language code, ISO-639-1. It is also the key used in `preview_urls`. |
| `data.items[].languages[].status` | `string` | zorunlu | Cloning state for this language. Orders are accepted only in a language whose clone is ready. |
| `data.items[].languages[].reference_duration_ms` | `integer` — nullable | zorunlu | Duration of the reference recording in milliseconds — the clone was trained on it. |
| `data.items[].languages[].model_version` | `integer` | zorunlu | Version of the trained model. It increments whenever the voice is retrained. |
| `data.items[].languages[].failure_reason` | `string` — nullable | zorunlu | Why cloning failed. `null` when there was no failure. |
| `data.items[].languages[].clone_started_at` | `string` — date-time — nullable | zorunlu | When cloning started, ISO 8601. |
| `data.items[].languages[].clone_completed_at` | `string` — date-time — nullable | zorunlu | When cloning finished, ISO 8601. `null` means it is still running or it failed. |
| `data.items[].languages[].updated_at` | `string` — date-time — nullable | zorunlu | When the language version last changed, ISO 8601. |
| `data.items[].preview_urls` | `object` | zorunlu | Preview clips by language: the key is a language code, the value a temporary audio link or `null` when there is no preview for that language. The links live for about a minute. |
| `data.items[].preview_urls.*` | `string` — rastgele anahtarlar — nullable | — |  |
| `data.current_page` | `integer` | zorunlu | Current page number, starting from one. |
| `data.last_page` | `integer` | zorunlu | Number of the last page. The walk is over once `current_page` equals `last_page`. |
| `data.per_page` | `integer` | zorunlu | Page size the server applied. |
| `data.total` | `integer` | zorunlu | Total number of records matching the filter. |

**Örnek**

```json
{
  "success": true,
  "message": "Success",
  "data": {
    "items": [
      {
        "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": "Yt5Fq2Wm8XbNc4Rp",
        "display_name": "Sofia Podcast Host (RU)",
        "description": "Energetic bilingual host voice, cloned for podcast intros and interview segments.",
        "gender": "female",
        "accent": null,
        "default_language_code": "ru",
        "voice_status": "ready",
        "publication_status": "public",
        "allow_usage_in_orders": true,
        "preview_generated_at": "2026-06-20T13:40:00+00:00",
        "created_at": "2026-06-18T08:00:00+00:00",
        "updated_at": "2026-06-20T13:40:00+00:00",
        "tags": [
          {
            "id": 5,
            "code": "energetic",
            "name": "Energetic",
            "description": null,
            "color": null,
            "sort_order": 50
          },
          {
            "id": 2,
            "code": "female",
            "name": "Female",
            "description": null,
            "color": null,
            "sort_order": 20
          }
        ],
        "languages": [
          {
            "id": 4,
            "language_code": "ru",
            "status": "ready",
            "reference_duration_ms": 58000,
            "model_version": 1,
            "failure_reason": null,
            "clone_started_at": "2026-06-18T08:05:00+00:00",
            "clone_completed_at": "2026-06-18T08:30:00+00:00",
            "updated_at": "2026-06-18T08:30:00+00:00"
          }
        ],
        "preview_urls": {
          "ru": "https://s3.lumean.app/lumean/storage/lumvoice/voices/Yt5Fq2Wm8XbNc4Rp/previews/ru.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260620%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260620T134000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c"
        }
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 2
  }
}
```

### 401 — The key is missing, unknown, disabled or expired.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | Always `false` in error responses. |
| `message` | `string` | zorunlu | Error text in the key's language (set through the `X-Locale` header). |
| `data` | `null` — nullable | zorunlu | Always `null` when the request is rejected before processing. |

**Örnek**

```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.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `message` | `string` | zorunlu | Error overview. |

**Örnek**

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

### 422 — Validation error. Offending fields are listed in `errors`.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `message` | `string` | zorunlu | Errors overview. |
| `errors` | `object` | zorunlu | A detailed description of each field that failed validation. |
| `errors.*` | `array<string>` — rastgele anahtarlar | — |  |

**Örnek**

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

---

- Bu sayfa tarayıcıda: https://lumean.app/tr/developers/docs/api/get-voices-public
- Makine tarafından okunabilir tam başvuru: https://api.lumean.app/docs/llm.md