---
title: "GET /voices/filters — Voice Catalogue Filters"
url: https://lumean.app/en/developers/docs/api/get-voices-filters
locale: en
description: "Voice Catalogue Filters"
generated: 2026-11-17
operationId: voiceCatalog.filters
method: GET
path: /voices/filters
scopes: [voices.read]
spec_version: 1.0.0
---

# GET /voices/filters

**Voice Catalogue Filters**

Descriptions of the filters of the chosen provider's voice catalogue: the parameter key,
a label, the kind (`text`, `select`, `multiselect`) and the allowed values with counts.
Pass `provider` (`elevenlabs`, `heygen`, `cartesia`, `fishaudio`, `lumvoice`) — the same
values as in `GET /voices?provider=…`.

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

- Required scope: `voices.read`

## Request

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

## Parameters

| Field | In | Type | Req. | Description |
| --- | --- | --- | --- | --- |
| `provider` | query | `string` — `elevenlabs` · `heygen` · `cartesia` · `fishaudio` · `lumvoice` | required | Voice provider: `elevenlabs`, `heygen`, `cartesia`, `fishaudio` or `lumvoice`. |
| `X-Locale` | header | `string` | — | Language of the localised texts in the response (`message`, labels, failure reasons), an ISO-639-1 code. Optional; without it — the key owner’s account language, then `Accept-Language`, then the default language. An unknown or unsupported code is skipped as if it were absent. |
| `X-Timezone` | header | `string` | — | IANA time zone (`Europe/Moscow`) in which the response shows moments in time — ISO-8601 with an offset. Optional; without it dates come in UTC. An invalid zone is ignored. The server returns the applied zone in the response header of the same name. |

## 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` | `object` | required | The response payload. |
| `data.provider` | `string` | required | The provider whose filters are described. |
| `data.filters` | `array<any>` | required | Filters of the provider’s voice catalogue. |

**Example**

```json
{
  "success": true,
  "message": "Success",
  "data": {
    "provider": "cartesia",
    "filters": [
      {
        "key": "search",
        "label": "Search",
        "type": "text",
        "options": null
      },
      {
        "key": "language",
        "label": "Language",
        "type": "select",
        "options": [
          {
            "value": "ru",
            "label": "ru",
            "count": 58
          },
          {
            "value": "en",
            "label": "en",
            "count": 214
          }
        ]
      },
      {
        "key": "gender",
        "label": "Gender",
        "type": "select",
        "options": [
          {
            "value": "female",
            "label": "female",
            "count": 150
          },
          {
            "value": "male",
            "label": "male",
            "count": 122
          }
        ]
      }
    ]
  }
}
```

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

### 404 — Not found, or not reachable with this key.

**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). |
| `reason` | `string` | — | Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text. |
| `error_code` | `string` | — | The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match. |

**Example**

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

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

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `message` | `string` | required | A summary of the validation errors in words, in the response language (`X-Locale`). |
| `errors` | `object` | required | A per-field breakdown: the key names a request field, the value lists the complaints about it. |
| `errors.*` | `array<string>` — arbitrary keys | — |  |

**Example**

```json
{
  "message": "string",
  "errors": {
    "key": [
      "string"
    ]
  }
}
```

---

- This page in the browser: https://lumean.app/en/developers/docs/api/get-voices-filters
- Full machine-readable reference: https://api.lumean.app/docs/llm.md
