Skip to content
Lumean API
GET/voices/cartesia/clones

My Cartesia Voice Clones

The key owner's Cartesia voice clones, newest first. Archived clones are left out unless you pass status=archived.

voices.read

A clone in ready carries a voice_id — put it into tts_settings.voice_id of a Cartesia template. While the clone is pending/cloning, voice_id is null.

The list does not check the subscription: an expired subscription never hides the clones already created.

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/clones
  • CartesiaVoiceCloneStatusin queryoptional

    Only clones in this status. Without it — everything except archived; archived clones show up only with status=archived.

    Allowed values
  • stringin queryoptional≤ 255 chars

    Search by clone name (display_name).

  • integerin queryoptional≥ 1

    Page number, starting at 1.

  • integerin queryoptional1..100

    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": "01a10e08-2ee3-73c2-88b2-8df2bcef9d1d",
        "provider": "cartesia",
        "display_name": "Narrator (my voice)",
        "language": "ru",
        "description": null,
        "status": "ready",
        "voice_id": "6afd76cb-2663-46f7-8f74-85221ce58c56",
        "attempts": 1,
        "error": null,
        "created_at": "2026-10-05T18:02:11+00:00",
        "completed_at": "2026-10-05T18:03:40+00:00",
        "failed_at": null,
        "banned_at": null,
        "ban_reason": null
      },
      {
        "id": "01a10e08-2ee5-702c-b492-243c88fd966f",
        "provider": "cartesia",
        "display_name": "Noisy sample",
        "language": "ru",
        "description": null,
        "status": "failed",
        "voice_id": null,
        "attempts": 1,
        "error": {
          "reason": "processing_error",
          "message": "The provider rejected the sample."
        },
        "created_at": "2026-10-05T17:40:02+00:00",
        "completed_at": null,
        "failed_at": "2026-10-05T17:41:15+00:00",
        "banned_at": null,
        "ban_reason": null
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "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

Your Cartesia voice clones on this page, newest first.

array<CartesiaVoiceClone>CartesiaVoiceClone
array item
idrequired

Clone UUID. Use it in /voices/cartesia/clones/{voiceClone}/… paths; it does NOT go into a template — voice_id does.

string
providerrequired

Clone provider — always cartesia.

Valuescartesia
string
display_namerequired

Clone name given at creation.

string
languagerequired

Language of the sample (ISO 639-1), or null if none was sent.

string
descriptionrequired

Your description of the clone, or null.

string
statusrequired

Status: pending → cloning → ready or failed; archived — retired by the owner; banned — blocked by a moderator. Only ready can be used for narration.

string
voice_idrequired

The Cartesia voice id — the value for tts_settings.voice_id of a template with service_key: cartesia. Present only for ready, otherwise null.

string
attemptsrequired

Cloning attempt number: 1 on creation, +1 for every retry.

integer
errorrequired

Why the last attempt failed; null while there has been no failure.

nullable
object
reasonrequired

Machine-readable failure code: processing_error, max_retries, network, timeout, dispatch_failed. Retry with POST /voices/cartesia/clones/{voiceClone}/retry; if processing_error keeps coming back, use a different sample.

string
messagerequired

Human-readable explanation of the failure, or null. Branch on reason, not on this text.

string
created_atrequired

When the clone was created.

string
completed_atrequired

When the clone became ready; null until then.

string
failed_atrequired

When the last attempt failed; null if it has not.

string
banned_atrequired

When a moderator banned the clone (status = banned); null if it is not banned.

string
ban_reasonrequired

Reason for the ban given by the moderator, or null. A banned clone can be neither used nor archived.

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
422

Validation error, for example an unknown status or per_page above 100. 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

Feed this page to an AI

Open .mdllm.md

spec 0.0.1