---
title: "POST /voices/{provider}/clones — Create Voice Clone"
url: https://lumean.app/en/developers/docs/api/post-voices-provider-clones
locale: en
description: "Create Voice Clone"
generated: 2026-11-17
operationId: voiceClone.store
method: POST
path: "/voices/{provider}/clones"
scopes: [voices.write]
spec_version: 1.0.0
---

# POST /voices/{provider}/clones

**Create Voice Clone**

Clones a voice from a sample recording for the chosen provider (`provider`: `cartesia`
or `fishaudio`; the clone cap is counted separately for each). The sample goes base64-encoded (a data URI
is fine too) into the `reference_audio` field of the JSON body, up to 20 MB;
`consent_biometric: true` (consent to biometric data processing) and `voice_owner`
(`self` or `third_party`) are recorded in the consent journal; the former
`consent_confirmed: true` is still accepted instead until consents become mandatory.

Cloning is asynchronous. The `201` response comes back at once with the clone in
`pending` (or straight away in `failed` with `error.reason: dispatch_failed` if the
queue is unavailable — then retry via
`POST /voices/{provider}/clones/{voiceClone}/retry`). After that it goes `pending` →
`cloning` → `ready` (or `failed`). If the sample sounds like, but not certainly, the voice of
a public artist on the protected list, the clone is created in `review` ("under
review"): it takes a slot of the cap and is not sent to the provider until a moderator
approves it (then `pending` → …) or blocks it (`banned`). Progress arrives as the `voice_clone.updated`
WebSocket event on `private-cartesia-voice-clones.{userId}` for Cartesia or
`private-fishaudio-voice-clones.{userId}` for Fish Audio; without WebSocket, poll
`GET /voices/{provider}/clones`.

Checks, in order: access to the service (`404 service_not_found`), subscription
(`402 no_subscription`) — a live subscription that includes the provider's service
(Cartesia or Fish Audio) is required only if that service is closed to paying from
the balance; otherwise cloning works without one — and the clone cap (`422 voice_clone_quota_exceeded`, the `max` field holds the
cap): 2 clones without a subscription (the fallback cap), the plan's cap with one. An
exhausted token quota does not block cloning.

The providers differ in the `language` field: Cartesia accepts one of its 42 language
codes, Fish Audio any two-letter ISO 639-1 code. Everything else (sample up to 20 MB,
formats, consents) is the same.

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

- Required scope: `voices.write`

## Request

```bash
curl -X POST '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. |
| `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` | `CartesiaVoiceClone` | required | The response payload. |
| `data.id` | `string` | required | Clone UUID. Use it in `/voices/cartesia/clones/{voiceClone}/…` paths; it does NOT go into a template — `voice_id` does. |
| `data.provider` | `string` — `cartesia` | required | Clone provider — always `cartesia`. |
| `data.display_name` | `string` | required | Clone name given at creation. |
| `data.language` | `string` — nullable | required | Language of the sample (ISO 639-1), or `null` if none was sent. |
| `data.description` | `string` — nullable | required | Your description of the clone, or `null`. |
| `data.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.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.attempts` | `integer` | required | Cloning attempt number: 1 on creation, +1 for every retry. |
| `data.error` | `object` — nullable | required | Why the last attempt failed; `null` while there has been no failure. |
| `data.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.error.message` | `string` — nullable | required | Human-readable explanation of the failure, or `null`. Branch on `reason`, not on this text. |
| `data.created_at` | `string` — date-time — nullable | required | When the clone was created. |
| `data.completed_at` | `string` — date-time — nullable | required | When the clone became `ready`; `null` until then. |
| `data.failed_at` | `string` — date-time — nullable | required | When the last attempt failed; `null` if it has not. |
| `data.banned_at` | `string` — date-time — nullable | required | When a moderator banned the clone (`status = banned`); `null` if it is not banned. |
| `data.ban_reason` | `string` — nullable | required | Reason for the ban given by the moderator, or `null`. A banned clone can be neither used nor archived. |

**Example**

```json
{
  "success": true,
  "message": "string",
  "data": {
    "id": "string",
    "provider": "string",
    "display_name": "string",
    "language": "string",
    "description": "string",
    "status": "string",
    "voice_id": "string",
    "attempts": 1,
    "error": {
      "reason": "string",
      "message": "string"
    },
    "created_at": "2026-07-17T12:34:56+00:00",
    "completed_at": "2026-07-17T12:34:56+00:00",
    "failed_at": "2026-07-17T12:34:56+00:00",
    "banned_at": "2026-07-17T12:34:56+00:00",
    "ban_reason": "string",
    "user_id": 1,
    "user": {
      "id": 1,
      "email": "string",
      "is_voice_clone_banned": true,
      "voice_clone_banned_at": "2026-07-17T12:34:56+00:00"
    },
    "work_item_id": "string",
    "cartesia_account_id": 1,
    "has_reference_audio": true,
    "consent_confirmed_at": "2026-07-17T12:34:56+00:00",
    "dispatched_at": "2026-07-17T12:34:56+00:00",
    "started_at": "2026-07-17T12:34:56+00:00",
    "archived_at": "2026-07-17T12:34:56+00:00",
    "banned_by_admin_id": 1,
    "protected_voice_match": {
      "hit_id": 1,
      "kind": "string",
      "protected_voice": {
        "id": 1,
        "name": "string"
      },
      "z": 1,
      "cosine": 1,
      "resolved_at": "string",
      "created_at": "string"
    },
    "updated_at": "2026-07-17T12:34:56+00:00"
  }
}
```

### 201 — Created. `data` holds the new object in full.

**Example**

```json
{
  "success": true,
  "message": "Success",
  "data": {
    "id": "01a10e08-27fe-716f-b428-6bc739602ca6",
    "provider": "cartesia",
    "display_name": "My voice",
    "language": "ru",
    "description": null,
    "status": "pending",
    "voice_id": null,
    "attempts": 1,
    "error": null,
    "created_at": "2026-10-06T09:15:00+00:00",
    "completed_at": null,
    "failed_at": null,
    "banned_at": null,
    "ban_reason": null
  }
}
```

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

### 402 — No live subscription that includes the provider's service (Cartesia or Fish Audio; `reason: no_subscription`). Returned only if that service is closed to paying from the balance.

**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": "An active subscription is required.",
  "reason": "no_subscription",
  "error_code": "no_subscription"
}
```

### 403 — The key lacks the `voices.write` 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 provider's service (Cartesia or Fish Audio) 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 — Two different bodies share this code. Validation error: `{success: false, message, errors: {field: [text]}}` with no `reason` (a required field is missing, no `consent_biometric`/`consent_confirmed` consent, `language` is not allowed for the provider (Cartesia: one of its 42 codes; Fish Audio: a two-letter ISO 639-1 code), the sample is not valid base64, is larger than 20 MB or is not WAV/MP3/M4A/AAC/OGG/WebM/FLAC). Clone cap of the plan: `{success: false, message, reason: "voice_clone_quota_exceeded", error_code, max}` — `max` is the cap; archive a clone (`DELETE`) or move to a higher plan. The voice of a public artist on the protected list (a confident match): `{success: false, message, reason: "protected_voice_match", error_code, protected_voice: {id, name, photo_url}}` — the clone is not created and the sample is not stored; if it is your own voice or you have the owner's permission, contact support. Tell them apart by the presence of `reason`.

**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. |
| `errors` | `object` | — | A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`. |
| `errors.*` | `array<string>` — arbitrary keys | — |  |
| `reason` | `string` | — | Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text. |
| `error_code` | `string` | — | The same machine-readable code as in `reason` — a second name for the field. The values always match. |
| `max` | `integer` | — | Only with `reason: voice_clone_quota_exceeded` — the clone cap of your plan for the chosen provider (clones of the other provider do not count). Archive a clone you no longer need to free a slot. |
| `protected_voice` | `object` | — | Only with `reason: protected_voice_match` — the public artist from the protected list whose voice the sample matched. The clone is not created and the sample is not stored. |
| `protected_voice.id` | `integer` | required | Protected voice id. |
| `protected_voice.name` | `string` | required | Artist name. |
| `protected_voice.photo_url` | `string` — nullable | required | Artist photo; may be `null`. |

**Example**

```json
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "consent_confirmed": [
      "The consent confirmed field must be accepted."
    ],
    "reference_audio": [
      "The file is too large: 20 MB at most."
    ]
  }
}
```

### 429 — The clone rate limit is exceeded (`reason: rate_limit_exceeded`): by default 6 attempts per minute and 60 per day per user, shared with the web cabinet and LumVoice cloning. Every attempt counts, including one rejected by validation. Wait `retry_after` seconds (the `Retry-After` header).

**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). |
| `reason` | `string` | required | Machine-readable failure reason — branch on this, 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; branch on either. |
| `retry_after` | `integer` — nullable | — | How many seconds to wait before retrying (the same value is in the `Retry-After` header). |

**Example**

```json
{
  "success": false,
  "message": "Too many attempts. Please wait a moment and try again.",
  "reason": "rate_limit_exceeded",
  "error_code": "rate_limit_exceeded",
  "retry_after": 30
}
```

---

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