Açıklamalar İngilizce

Bölümün arayüzü dilinize çevrildi, ancak işlem, şema ve hata açıklamaları yalnızca Rusça ve İngilizce mevcut — burada İngilizce sürüm gösteriliyor.

POST/voices/fishaudio/clones

Create Fish Audio 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.

voices.write 402 PAYG 429 limitler

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/fishaudio/clones/{voiceClone}/retry). After that it goes pending → cloning → ready (or failed). Progress arrives as the voice_clone.updated WebSocket event on private-fishaudio-voice-clones.{userId}; without WebSocket, poll GET /voices/fishaudio/clones.

Checks, in order: access to the service (404 service_not_found), subscription (402 no_subscription) — a live subscription that includes Fish Audio 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. The rules are the same as Cartesia's; the clone cap is counted separately. An exhausted token quota does not block cloning.

Required key permission: voices.write.

Bu sayfada(3)

İstek gövdesi

application/jsonzorunlu

A new Fish Audio voice clone: a base64 sample recording plus consent to use the voice. Accepted as application/json.

Senaryolar

Sample as plain base64 Sample as a data URI, minimal fields

Sample as plain base64

{
  "display_name": "My voice",
  "reference_audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
  "language": "ru",
  "description": "Audiobook narrator",
  "consent_biometric": true,
  "voice_owner": "self"
}

Alanlar

display_namezorunlu

Clone name — visible only to you, up to 128 characters.

≤ 128 karakter

string

Örnek Мой голос

reference_audiozorunlu

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.

string

Örnek UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=

consent_confirmedzorunlu

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.

string

Örnek true

languageisteğe bağlı

A reference label for the clone, a two-letter ISO 639-1 code (ru, en, …). Fish Audio voices have no language of their own and the label is not sent to the provider.

null olabilirdesen: ^[a-z]{2}$

string

Örnek ru

descriptionisteğe bağlı

Your description of the clone, up to 500 characters.

null olabilir≤ 500 karakter

string

consent_biometricisteğe bağlı

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.

boolean

Örnek true

voice_owneristeğe bağlı

Whose voice is in the sample: self — yours, third_party — someone else's, and you hold their consent.

null olabilir

Değerlerselfthird_party

string

Örnek self

Olası yanıtlar

201

Created. data holds the new object in full.

Gövde örneği

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

Yanıt alanları

successzorunlu

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

messagezorunlu

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

datazorunlu

The new clone — in pending (or straight away in failed with error.reason: dispatch_failed if the queue is unavailable).

FishAudioVoiceCloneFishAudioVoiceClone

idzorunlu

Clone UUID. Use it in /voices/fishaudio/clones/{voiceClone}/… paths; it does NOT go into a template — voice_id does.

string

providerzorunlu

Clone provider — always fishaudio.

Değerlerfishaudio

string

display_namezorunlu

Clone name given at creation.

string

languagezorunlu

Reference language label (ISO 639-1), or null if none was sent. It does not affect cloning.

string

descriptionzorunlu

Your description of the clone, or null.

string

statuszorunlu

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_idzorunlu

The Fish Audio voice id (a 32-character hex string, not a UUID) — the value for tts_settings.voice_id of a template with service_key: fishaudio. Present only for ready, otherwise null.

string

attemptszorunlu

Cloning attempt number: 1 on creation, +1 for every retry.

integer

errorzorunlu

Why the last attempt failed; null while there has been no failure.

null olabilir

object

reasonzorunlu

Machine-readable failure code: processing_error, max_retries, network, timeout, dispatch_failed, unbanned (the clone was unbanned but had no voice). Retry with POST /voices/fishaudio/clones/{voiceClone}/retry; if processing_error keeps coming back, use a different sample.

string

messagezorunlu

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

string

created_atzorunlu

When the clone was created.

string

completed_atzorunlu

When the clone became ready; null until then.

string

failed_atzorunlu

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

string

banned_atzorunlu

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

string

ban_reasonzorunlu

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

string

401

The key is missing, unknown, disabled or expired.

Bu yanıtı çözümle

Gövde örneği

{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}

Yanıt alanları

successzorunlu

Always false in error responses.

boolean

messagezorunlu

Error text in the key's language (set through the X-Locale header).

string

datazorunlu

Always null when the request is rejected before processing.

null olabilir

null

402

No live subscription that includes Fish Audio (reason: no_subscription). Returned only if the service is closed to paying from the balance.

Bu yanıtı çözümle

Gövde örneği

{
  "success": false,
  "message": "An active subscription is required.",
  "reason": "no_subscription",
  "error_code": "no_subscription"
}

Yanıt alanları

successzorunlu

Always false in error responses.

boolean

messagezorunlu

The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

string

reasonzorunlu

Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.

string

error_codezorunlu

The same machine-readable code as in reason — a second name for the field. The values always match.

string

403

The key lacks the voices.write permission.

Bu yanıtı çözümle

Gövde örneği

{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}

Yanıt alanları

successzorunlu

Always false in error responses.

boolean

messagezorunlu

Error text in the key's language (set through the X-Locale header).

string

404

The Fish Audio service is closed to the key owner (reason: service_not_found).

Bu yanıtı çözümle

Gövde örneği

{
  "success": false,
  "message": "Service not found.",
  "reason": "service_not_found",
  "error_code": "service_not_found"
}

Yanıt alanları

successzorunlu

Always false in error responses.

boolean

messagezorunlu

The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

string

reasonzorunlu

Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.

string

error_codezorunlu

The same machine-readable code as in reason — a second name for the field. The values always match.

string

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 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. Tell them apart by the presence of reason.

Bu yanıtı çözümle

Gövde örneği

{
  "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."
    ]
  }
}

Yanıt alanları

messagezorunlu

Errors overview.

string

errorszorunlu

A detailed description of each field that failed validation.

object

*isteğe bağlı

rastgele anahtarlar

array<string>

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

Bu yanıtı çözümle

Gövde örneği

{
  "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
}

Yanıt alanları

successzorunlu

Always false in error responses.

boolean

messagezorunlu

Error text in the key's language (set through the X-Locale header).

string

reasonzorunlu

Machine-readable failure reason — branch on this, not on the message text.

string

error_codezorunlu

The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.

string

retry_afteristeğe bağlı

How many seconds to wait before retrying (the same value is in the Retry-After header).

null olabilir

integer

Düz anlatımla

Realtime: connecting and subscribing

Nesneler

FishAudioVoiceClone

Komşu işlemler

Daha fazla

Bu sayfayı yapay zekâya verin

.md sürümünü aç llm.md

spesifikasyon 0.0.1

İstek gövdesi

Olası yanıtlar

İlgili içerik

Bu sayfayı yapay zekâya verin