---
title: "GET /voices/{provider}/clones — My Voice Clones"
url: https://lumean.app/en/developers/docs/api/get-voices-provider-clones
locale: en
description: "My Voice Clones"
generated: 2026-11-17
operationId: voiceClone.index
method: GET
path: "/voices/{provider}/clones"
scopes: [voices.read]
spec_version: 1.0.0
---

# 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`.

- Required scope: `voices.read`

## Request

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

## Parameters

| Field | In | Type | Req. | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | `string` — `cartesia` · `fishaudio` | required | 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. |
| `status` | query | `string` — `review` · `pending` · `cloning` · `ready` · `failed` · `archived` · `banned` — ≤ 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`. |
| `search` | query | `string` — ≤ 255 chars | — | Search by clone name (`display_name`). |
| `page` | query | `integer` — ≥ 1 | — | Page number, starting at `1`. |
| `per_page` | query | `integer` — 1..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`. |
| `X-Locale` | header | `string` | — | Language of the localised texts in the response (`message`, labels, failure reasons), an ISO-639-1 code. Optional; without it — the key owner’s account language, then `Accept-Language`, then the default language. An unknown or unsupported code is skipped as if it were absent. |
| `X-Timezone` | header | `string` | — | IANA time zone (`Europe/Moscow`) in which the response shows moments in time — ISO-8601 with an offset. Optional; without it dates come in UTC. An invalid zone is ignored. The server returns the applied zone in the response header of the same name. |

## 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<CartesiaVoiceClone>` | required | Your voice clones of the chosen provider (`cartesia` or `fishaudio`) on this page, newest first. |
| `data.items[].id` | `string` | required | Clone UUID. Use it in `/voices/cartesia/clones/{voiceClone}/…` paths; it does NOT go into a template — `voice_id` does. |
| `data.items[].provider` | `string` — `cartesia` | required | Clone provider — always `cartesia`. |
| `data.items[].display_name` | `string` | required | Clone name given at creation. |
| `data.items[].language` | `string` — nullable | required | Language of the sample (ISO 639-1), or `null` if none was sent. |
| `data.items[].description` | `string` — nullable | required | Your description of the clone, or `null`. |
| `data.items[].status` | `string` | required | Status: `pending` → `cloning` → `ready` or `failed`; `archived` — retired by the owner; `banned` — blocked by a moderator. Only `ready` can be used for narration. |
| `data.items[].voice_id` | `string` — nullable | required | The Cartesia voice id — the value for `tts_settings.voice_id` of a template with `service_key: cartesia`. Present only for `ready`, otherwise `null`. |
| `data.items[].attempts` | `integer` | required | Cloning attempt number: 1 on creation, +1 for every retry. |
| `data.items[].error` | `object` — nullable | required | Why the last attempt failed; `null` while there has been no failure. |
| `data.items[].error.reason` | `string` — nullable | required | 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. |
| `data.items[].error.message` | `string` — nullable | required | Human-readable explanation of the failure, or `null`. Branch on `reason`, not on this text. |
| `data.items[].created_at` | `string` — date-time — nullable | required | When the clone was created. |
| `data.items[].completed_at` | `string` — date-time — nullable | required | When the clone became `ready`; `null` until then. |
| `data.items[].failed_at` | `string` — date-time — nullable | required | When the last attempt failed; `null` if it has not. |
| `data.items[].banned_at` | `string` — date-time — nullable | required | When a moderator banned the clone (`status = banned`); `null` if it is not banned. |
| `data.items[].ban_reason` | `string` — nullable | required | Reason for the ban given by the moderator, or `null`. A banned clone can be neither used nor archived. |
| `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": "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
  }
}
```

### 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."
}
```

### 422 — Validation error, for example an unknown `status` or `per_page` above 100. Offending fields are listed in `errors`.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | A summary of the validation errors in words, in the response language (`X-Locale`). |
| `errors` | `object` | required | A per-field breakdown: the key names a request field, the value lists the complaints about it. |
| `errors.*` | `array<string>` — arbitrary keys | — |  |

**Example**

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

---

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