---
title: "GET /voices/cartesia — Cartesia Voices"
url: https://lumean.app/developers/docs/api/get-voices-cartesia
locale: ru
description: "Cartesia Voices"
generated: 2026-10-17
operationId: cartesiaVoice.voices
method: GET
path: /voices/cartesia
scopes: [voices.read]
spec_version: 0.0.1
---

# GET /voices/cartesia

**Cartesia Voices**

Каталог голосов сервиса озвучки Cartesia: активные голоса с фильтрами по языку
(ISO 639-1), полу и строке поиска. `voice_id` из ответа кладётся в
`tts_settings.voice_id` шаблона с `service_key: cartesia`; параметр `voice_id`
находит один голос по точному id — подпись голоса, уже выбранного в шаблоне.

Свой клонированный голос в каталоге не появляется — его `voice_id` отдаёт
`GET /voices/cartesia/clones` (только у клона в статусе `ready`). Голос,
склонированный вне Lumean (например, на cartesia.ai), тоже принимается: его id
у Cartesia (UUID) кладётся в `tts_settings.voice_id` как есть.

Если сервис закрыт для владельца ключа (закрытый тест), ответ — `404`
с `reason: service_not_found`.

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

- Право ключа: `voices.read`

## Запрос

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

## Параметры

| Поле | Где | Тип | Обяз. | Описание |
| --- | --- | --- | --- | --- |
| `language` | query | `string` — ≤ 16 симв. | — | Язык голоса, код ISO 639-1 (`ru`, `en`, …). |
| `gender` | query | `string` — ≤ 32 симв. | — | Пол голоса в написании каталога Cartesia (`masculine`, `feminine`, `gender_neutral`). |
| `search` | query | `string` — ≤ 255 симв. | — | Поиск по названию и описанию голоса. |
| `voice_id` | query | `string` — ≤ 255 симв. | — | Точный `voice_id` голоса — найти подпись и превью голоса, уже выбранного в шаблоне, без перебора страниц. Снятый с каталога голос в ответ не попадает: пустой список. |
| `page` | query | `integer` — ≥ 1 | — | Номер страницы, начиная с `1`. |
| `per_page` | query | `integer` — 1..200 | — | Сколько записей вернуть на странице. Метаданные пагинации лежат рядом с `items`: `current_page`, `last_page`, `per_page`, `total`. |

## Тело запроса

Тела нет.

## Ответы

### 200 — Успех. Полезная нагрузка — в поле `data`.

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь `true`, а ошибка приходит телом другой формы, где этого поля может не быть вовсе. |
| `message` | `string` | обяз. | Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются. |
| `data` | `object` | обяз. | Полезная нагрузка ответа. |
| `data.items` | `array<CartesiaVoice>` | обяз. | Голоса каталога Cartesia на этой странице. |
| `data.items[].id` | `string` | обяз. | Внутренний id записи каталога. Для озвучки не нужен — в шаблон идёт `voice_id`. |
| `data.items[].voice_id` | `string` | обяз. | Идентификатор голоса Cartesia — значение для `tts_settings.voice_id` шаблона с `service_key: cartesia`. |
| `data.items[].name` | `string` | обяз. | Название голоса. |
| `data.items[].description` | `string` | обяз. | Описание голоса от Cartesia либо `null`. |
| `data.items[].language` | `string` | обяз. | Язык голоса (ISO 639-1) либо `null`. |
| `data.items[].gender` | `string` | обяз. | Пол голоса: `masculine`, `feminine`, `gender_neutral` либо `null`. |
| `data.items[].preview_url` | `string` | обяз. | Ссылка на демо-запись голоса либо `null`. |
| `data.current_page` | `integer` | обяз. | Номер текущей страницы, с единицы. |
| `data.last_page` | `integer` | обяз. | Номер последней страницы. |
| `data.per_page` | `integer` | обяз. | Размер страницы, применённый сервером. |
| `data.total` | `integer` | обяз. | Сколько записей всего по фильтру. |

**Пример**

```json
{
  "success": true,
  "message": "Success",
  "data": {
    "items": [
      {
        "id": 12,
        "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091",
        "name": "Russian Narrator",
        "description": "Calm male narrator for audiobooks.",
        "language": "ru",
        "gender": "masculine",
        "preview_url": "https://files.cartesia.ai/previews/a0e99841-438c-4a64-b679-ae501e7d6091.wav"
      },
      {
        "id": 13,
        "voice_id": "2ee87190-8f84-4925-97da-e52547f9462c",
        "name": "Warm Storyteller",
        "description": null,
        "language": "ru",
        "gender": "feminine",
        "preview_url": null
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 50,
    "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."
}
```

### 404 — Сервис Cartesia закрыт для владельца ключа (`service_not_found`)

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `reason` | `string` | обяз. | Машиночитаемая причина бизнес-отказа (например, `input_expired`, `insufficient_balance`). Ветвите обработку по ней, а не по тексту `message`. |
| `error_code` | `string` | обяз. | Тот же машинный код, что в `reason`, — второе имя поля. Значения всегда совпадают. |

**Пример**

```json
{
  "success": false,
  "message": "Service not found.",
  "reason": "service_not_found",
  "error_code": "service_not_found"
}
```

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

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Errors overview. |
| `errors` | `object` | обяз. | A detailed description of each field that failed validation. |
| `errors.*` | `array<string>` — произвольные ключи | — |  |

**Пример**

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

---

- Эта же страница в браузере: https://lumean.app/developers/docs/api/get-voices-cartesia
- Машинный справочник целиком: https://api.lumean.app/docs/llm.md