---
title: "GET /voices/cartesia — Cartesia Voices"
url: https://lumean.app/en/developers/docs/api/get-voices-cartesia
locale: en
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**

The voice catalogue of the Cartesia text-to-speech service: active voices, filterable
by language (ISO 639-1), gender and a search string. Put the `voice_id` from the
response into `tts_settings.voice_id` of a template with `service_key: cartesia`;
the `voice_id` parameter finds one voice by its exact id — the name of a voice already
chosen in a template.

Your own cloned voice does not show up in the catalogue — its `voice_id` comes from
`GET /voices/cartesia/clones` (only once the clone is `ready`). A voice cloned
outside Lumean (for example on cartesia.ai) is accepted too: put its Cartesia id
(a UUID) into `tts_settings.voice_id` as is.

If the service is closed to the key owner (closed testing), the answer is `404`
with `reason: service_not_found`.

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

- Required scope: `voices.read`

## Request

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

## Parameters

| Field | In | Type | Req. | Description |
| --- | --- | --- | --- | --- |
| `language` | query | `string` — ≤ 16 chars | — | Voice language, an ISO 639-1 code (`ru`, `en`, …). |
| `gender` | query | `string` — ≤ 32 chars | — | Voice gender in the Cartesia catalogue spelling (`masculine`, `feminine`, `gender_neutral`). |
| `search` | query | `string` — ≤ 255 chars | — | Search by voice name and description. |
| `voice_id` | query | `string` — ≤ 255 chars | — | Exact voice `voice_id` — look up the name and preview of a voice already chosen in a template without paging through the catalogue. A voice withdrawn from the catalogue is not returned: the list is empty. |
| `page` | query | `integer` — ≥ 1 | — | Page number, starting at `1`. |
| `per_page` | query | `integer` — 1..200 | — | 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` | `object` | required | The response payload. |
| `data.items` | `array<CartesiaVoice>` | required | Cartesia catalogue voices on this page. |
| `data.items[].id` | `string` | required | Internal id of the catalogue entry. Not needed for narration — `voice_id` goes into the template. |
| `data.items[].voice_id` | `string` | required | The Cartesia voice id — the value for `tts_settings.voice_id` of a template with `service_key: cartesia`. |
| `data.items[].name` | `string` | required | Voice name. |
| `data.items[].description` | `string` | required | Voice description from Cartesia, or `null`. |
| `data.items[].language` | `string` | required | Voice language (ISO 639-1), or `null`. |
| `data.items[].gender` | `string` | required | Voice gender: `masculine`, `feminine`, `gender_neutral`, or `null`. |
| `data.items[].preview_url` | `string` | required | Link to a voice preview recording, or `null`. |
| `data.current_page` | `integer` | required | Current page number, starting from one. |
| `data.last_page` | `integer` | required | Number of the 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": "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 — 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 `voices.read` permission.

**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 — The Cartesia service is closed to the key owner (`reason: service_not_found`).

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes. |
| `reason` | `string` | required | Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text. |
| `error_code` | `string` | required | The same machine-readable code as in `reason` — a second name for the field. The values always match. |

**Example**

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

### 422 — Validation error, for example `per_page` above 200. 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<string>` — arbitrary keys | — |  |

**Example**

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

---

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