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.
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.
- stringin pathrequired
Voice provider whose clones you work with:
cartesiaorfishaudio. 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
Possible responses
200Success. The payload is in data.
Success. The payload is in data.
{
"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"
}
}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.
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.
datarequiredThe response payload.
CartesiaVoiceCloneCartesiaVoiceClone
The response payload.
Clone UUID. Use it in /voices/cartesia/clones/{voiceClone}/… paths; it does NOT go into a template — voice_id does.
Clone provider — always cartesia.
Clone name given at creation.
Language of the sample (ISO 639-1), or null if none was sent.
Your description of the clone, or null.
Status: pending → cloning → ready or failed; archived — retired by the owner; banned — blocked by a moderator. Only ready can be used for narration.
The Cartesia voice id — the value for tts_settings.voice_id of a template with service_key: cartesia. Present only for ready, otherwise null.
Cloning attempt number: 1 on creation, +1 for every retry.
errorrequiredWhy the last attempt failed; null while there has been no failure.
nullableobject
Why the last attempt failed; null while there has been no failure.
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.
Human-readable explanation of the failure, or null. Branch on reason, not on this text.
When the clone was created.
When the clone became ready; null until then.
When the last attempt failed; null if it has not.
When a moderator banned the clone (status = banned); null if it is not banned.
Reason for the ban given by the moderator, or null. A banned clone can be neither used nor archived.
201Created. data holds the new object in full.
Created. data holds the new object in full.
{
"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
}
}401The key is missing, unknown, disabled or expired.
The key is missing, unknown, disabled or expired.
{
"success": false,
"message": "API key is missing. Provide it in the X-API-KEY header.",
"data": null
}Always false in error responses.
Error text in the key's language (set through the X-Locale header).
Always null when the request is rejected before processing.
402No 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.
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.
{
"success": false,
"message": "An active subscription is required.",
"reason": "no_subscription",
"error_code": "no_subscription"
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
403The key lacks the voices.write permission.
The key lacks the voices.write permission.
{
"success": false,
"message": "This API key does not have permission to perform this action."
}Always false in error responses.
Error text in the key's language (set through the X-Locale header).
404The provider's service (Cartesia or Fish Audio) is closed to the key owner (reason: service_not_found).
The provider's service (Cartesia or Fish Audio) is closed to the key owner (reason: service_not_found).
{
"success": false,
"message": "Service not found.",
"reason": "service_not_found",
"error_code": "service_not_found"
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
422Two 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.
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.
{
"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."
]
}
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
errorsoptionalA 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.
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.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
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_voiceoptionalOnly 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.
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.
Artist name.
Artist photo; may be null.
429The 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).
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).
{
"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
}Always false in error responses.
Error text in the key's language (set through the X-Locale header).
Machine-readable failure reason — branch on this, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.
How many seconds to wait before retrying (the same value is in the Retry-After header).
Nearby
This page for AI
API version 1.0.0