Skip to content
Lumean
GET/voices/{provider}/clones

My Voice Clones

The key owner's voice clones of the chosen provider (provider: cartesia or fishaudio), newest first. Archived clones are left out unless you pass status=archived.

A clone in ready carries a voice_id — put it into tts_settings.voice_id of a template of the same provider (Cartesia or Fish Audio). 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.

Parameters

Values go straight into the request line, and the URL is built for you. Below are each parameter’s type, whether it is required, and its allowed values.

GEThttps://api.lumean.app/api/public/voices//clones
  • stringin pathrequired

    Voice provider whose clones you work with: cartesia or fishaudio. Any other value does not match the route (404). The clone cap, the subscription rule and the clone ids are separate for each provider.

    The value goes straight into the request line above.

    Allowed values
  • stringin queryoptional≤ 32 chars

    Only clones in this status: review, pending, cloning, ready, failed, archived or banned. Without it — everything except archived; archived clones show up only with status=archived.

    Allowed values
  • integerin queryoptional≥ 1

    Page number, starting at 1.

  • integerin queryoptional1..100

    How many records to return per page. The page meta sits in data next to the items list: 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 voice clones of the chosen provider (cartesia or fishaudio) 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.

nullable
string
descriptionrequired

Your description of the clone, or null.

nullable
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.

nullable
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.

nullable
string
messagerequired

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

nullable
string
created_atrequired

When the clone was created.

nullabledate-time
string
completed_atrequired

When the clone became ready; null until then.

nullabledate-time
string
failed_atrequired

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

nullabledate-time
string
banned_atrequired

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

nullabledate-time
string
ban_reasonrequired

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

nullable
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
{
  "success": true,
  "message": "string",
  "errors": {}
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

A summary of the validation errors in words, in the response language (X-Locale).

string
errorsrequired

A per-field breakdown: the key names a request field, the value lists the complaints about it.

object
*optional
arbitrary keys
array<string>

This page for AI

Open .mdllm.md

API version 1.0.0