Skip to content
Lumean API
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.

voices.read

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.

On this page(3)

Parameters

The inputs live inside the request line: fill in a value and you get a ready URL. Below are the type, whether it is required and the allowed values of every parameter.

GEThttps://api.lumean.app/api/public/voices/cartesia
  • stringin queryoptional≤ 16 chars

    Voice language, an ISO 639-1 code (ru, en, …).

  • stringin queryoptional≤ 32 chars

    Voice gender in the Cartesia catalogue spelling (masculine, feminine, gender_neutral).

  • stringin queryoptional≤ 255 chars

    Search by voice name and description.

  • stringin queryoptional≤ 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.

  • integerin queryoptional≥ 1

    Page number, starting at 1.

  • integerin queryoptional1..200

    How many records to return per page. Pagination metadata sits next to items: current_page, last_page, per_page, total.

Possible responses

200

Success. The payload is in data.

Body example
{
  "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
  }
}
Response fields
successrequired

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.

boolean
messagerequired

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.

string
datarequired

The response payload.

object
itemsrequired

Cartesia catalogue voices on this page.

array<CartesiaVoice>CartesiaVoice
array item
idrequired

Internal id of the catalogue entry. Not needed for narration — voice_id goes into the template.

string
voice_idrequired

The Cartesia voice id — the value for tts_settings.voice_id of a template with service_key: cartesia.

string
namerequired

Voice name.

string
descriptionrequired

Voice description from Cartesia, or null.

string
languagerequired

Voice language (ISO 639-1), or null.

string
genderrequired

Voice gender: masculine, feminine, gender_neutral, or null.

string
preview_urlrequired

Link to a voice preview recording, or null.

string
current_pagerequired

Current page number, starting from one.

integer
last_pagerequired

Number of the last page.

integer
per_pagerequired

Page size the server applied.

integer
totalrequired

Total number of records matching the filter.

integer
401

The key is missing, unknown, disabled or expired.

Analyse this response
Body example
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
datarequired

Always null when the request is rejected before processing.

nullable
null
403

The key lacks the voices.read permission.

Analyse this response
Body example
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
404

The Cartesia service is closed to the key owner (reason: service_not_found).

Analyse this response
Body example
{
  "success": false,
  "message": "Service not found.",
  "reason": "service_not_found",
  "error_code": "service_not_found"
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

string
reasonrequired

Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.

string
error_coderequired

The same machine-readable code as in reason — a second name for the field. The values always match.

string
422

Validation error, for example per_page above 200. Offending fields are listed in errors.

Analyse this response
Body example
{
  "message": "string",
  "errors": {}
}
Response fields
messagerequired

Errors overview.

string
errorsrequired

A detailed description of each field that failed validation.

object
*optional
arbitrary keys
array<string>

Nearby

Neighbouring operations

Feed this page to an AI

Open .mdllm.md

spec 0.0.1