Açıklamalar İngilizce
Create Cartesia Voice Clone
Clones a voice from a sample recording. 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/cartesia/clones/{voiceClone}/retry). After that it goes pending →
cloning → ready (or failed). Progress arrives as the voice_clone.updated
WebSocket event on private-cartesia-voice-clones.{userId}; without WebSocket, poll
GET /voices/cartesia/clones.
Checks, in order: access to the service (404 service_not_found), subscription
(402 no_subscription) — a live subscription that includes Cartesia is required only
if the 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.
Required key permission: voices.write.
Bu sayfada(3)
İstek gövdesi
A new Cartesia voice clone: a base64 sample recording plus consent to use the voice.
Accepted as application/json.
{
"display_name": "My voice",
"reference_audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
"language": "ru",
"description": "Audiobook narrator",
"consent_biometric": true,
"voice_owner": "self"
}Alanlar
Clone name — visible only to you, up to 128 characters.
The voice sample in base64; a data URI (data:audio/wav;base64,…) works too. Up to
20 MB once decoded; any common audio format (WAV, MP3 and the like). It should be
clean speech by a single person, without music or noise.
The former checkbox "the voice is yours or you hold the right to use it". Needed only if consent_biometric: true is not sent; once consents become mandatory, send consent_biometric and voice_owner instead.
Language of the sample, an ISO 639-1 code from the list. Omitted — the default language of the worker.
Your description of the clone, up to 500 characters.
Consent to processing of biometric data — the voice sample (https://lumean.app/consent/biometric). Recorded in the consent journal together with the clone id. true — consent given.
Whose voice is in the sample: self — yours, third_party — someone else's, and you hold their consent.
Olası yanıtlar
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
}
}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.
datazorunluThe new clone — in pending (or straight away in failed with error.reason: dispatch_failed if the queue is unavailable).
CartesiaVoiceCloneCartesiaVoiceClone
The new clone — in pending (or straight away in failed with error.reason: dispatch_failed if the queue is unavailable).
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.
errorzorunluWhy the last attempt failed; null while there has been no failure.
null olabilirobject
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.
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 Cartesia (reason: no_subscription). Returned only if the service is closed to paying from the balance.
No live subscription that includes Cartesia (reason: no_subscription). Returned only if the 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 Cartesia service is closed to the key owner (reason: service_not_found).
The Cartesia service 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 one of the 42 codes, 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. 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 one of the 42 codes, 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. 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."
]
}
}Errors overview.
errorszorunluA detailed description of each field that failed validation.
object
A detailed description of each field that failed validation.
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).
İlgili içerik
Bu sayfayı yapay zekâya verin
spesifikasyon 0.0.1