POST/voices/fishaudio/clones

Клонирует голос по образцу записи. Образец — base64 (можно data URI) в поле reference_audio JSON-тела, до 20 МБ. Согласие: consent_biometric: true (на обработку биометрии — образца голоса) и voice_owner (self — ваш голос, third_party — чужой, есть согласие владельца) пишутся в журнал согласий вместе с id клона; прежний consent_confirmed: true принимается вместо них, пока согласия не стали обязательными.

voices.write 402 PAYG 429 лимиты

Клонирование асинхронное. Ответ 201 приходит сразу с клоном в статусе pending (или сразу failed с error.reason: dispatch_failed, если очередь недоступна — тогда повторите через POST /voices/fishaudio/clones/{voiceClone}/retry). Дальше pending → cloning → ready (или failed). Ход приходит WS-событием voice_clone.updated на канале private-fishaudio-voice-clones.{userId}; без WS — опрашивайте GET /voices/fishaudio/clones.

Проверки по порядку: доступ к сервису (404 service_not_found), подписка (402 no_subscription) — живая подписка с правом Fish Audio нужна, только если сервис закрыт для оплаты с баланса; иначе клонировать можно и без подписки, — потолок клонов (422 voice_clone_quota_exceeded, поле max — потолок): без подписки доступно 2 клона (запасной потолок), с подпиской — лимит тарифа. Те же правила, что у Cartesia. Исчерпанная квота токенов клону не мешает.

Требуемое право ключа: voices.write.

На этой странице(3)

Тело запроса

application/jsonобязательно

Новый клон голоса Fish Audio: образец записи в base64 и согласие на использование голоса. Принимается как application/json.

Сценарии

Образец — чистый base64 Образец — data URI, минимум полей

Образец — чистый base64

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

Поля

display_nameобязательное

Название клона — видно только вам, до 128 символов.

≤ 128 симв.

string

Пример Мой голос

reference_audioобязательное

Образец голоса в base64; data URI (data:audio/wav;base64,…) тоже подходит. До 20 МБ после декодирования; формат — обычная аудиозапись (WAV, MP3 и т. п.). Нужна чистая речь одного человека без музыки и шума.

string

Пример UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=

consent_confirmedобязательное

Прежняя галочка «это ваш голос или у вас есть право его использовать». Нужна, только если не передан consent_biometric: true; когда согласия станут обязательными, вместо неё — consent_biometric и voice_owner.

string

Пример true

languageнеобязательное

Справочная метка клона, двухбуквенный код ISO 639-1 (ru, en, …). У голоса Fish Audio своего языка нет, провайдеру метка не передаётся.

может быть nullшаблон: ^[a-z]{2}$

string

Пример ru

descriptionнеобязательное

Ваше описание клона, до 500 символов.

может быть null≤ 500 симв.

string

consent_biometricнеобязательное

Согласие на обработку биометрических данных — образца голоса (https://lumean.app/consent/biometric). Пишется в журнал согласий вместе с id клона. true — согласие дано.

boolean

Пример true

voice_ownerнеобязательное

Чей голос в образце: self — ваш, third_party — чужой, и у вас есть согласие его владельца.

может быть null

Значенияselfthird_party

string

Пример self

Возможные ответы

201

Клон поставлен в очередь

Пример тела

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

Поля ответа

successобязательное

Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь true, а ошибка приходит телом другой формы, где этого поля может не быть вовсе.

boolean

messageобязательное

Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются.

string

dataобязательное

Созданный клон — в статусе pending (или сразу failed с error.reason: dispatch_failed, если очередь недоступна).

FishAudioVoiceCloneFishAudioVoiceClone

idобязательное

UUID клона. Его подставляют в пути /voices/fishaudio/clones/{voiceClone}/…; в шаблон он НЕ идёт — туда идёт voice_id.

string

providerобязательное

Провайдер клона — всегда fishaudio.

Значенияfishaudio

string

display_nameобязательное

Название клона, заданное при создании.

string

languageобязательное

Справочная метка языка (ISO 639-1) либо null, если не передавалась. На клонирование не влияет.

string

descriptionобязательное

Ваше описание клона либо null.

string

statusобязательное

Статус: pending → cloning → ready либо failed; archived — снят владельцем; banned — заблокирован модератором. Озвучивать можно только ready.

string

voice_idобязательное

Идентификатор голоса Fish Audio (строка из 32 hex-символов, не UUID) — значение для tts_settings.voice_id шаблона с service_key: fishaudio. Есть только у ready, иначе null.

string

attemptsобязательное

Номер попытки клонирования: 1 при создании, +1 за каждый повтор.

integer

errorобязательное

Причина отказа последней попытки; null, пока отказа не было.

может быть null

object

reasonобязательное

Машинный код отказа: processing_error, max_retries, network, timeout, dispatch_failed, unbanned (клон разбанен, но голоса у него не было). Повторить попытку — POST /voices/fishaudio/clones/{voiceClone}/retry; если processing_error повторяется, смените образец.

string

messageобязательное

Пояснение к отказу для человека либо null. Ветвитесь по reason, а не по тексту.

string

created_atобязательное

Когда клон создан.

string

completed_atобязательное

Когда клон стал ready; null до этого.

string

failed_atобязательное

Когда последняя попытка завершилась отказом; null, если отказа нет.

string

banned_atобязательное

Когда клон заблокирован модератором (status = banned); null, если блокировки нет.

string

ban_reasonобязательное

Причина блокировки от модератора либо null. Заблокированный клон нельзя ни использовать, ни архивировать.

string

401

Невалидный или отсутствующий X-API-KEY

Разобрать этот ответ

Пример тела

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

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

dataобязательное

Всегда null, когда запрос отклонён до обработки.

может быть null

null

402

Нет живой подписки с правом Fish Audio (no_subscription) — только если сервис закрыт для оплаты с баланса

Разобрать этот ответ

Пример тела

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

Поля ответа

successобязательное

Всегда false у ошибок.

boolean

messageобязательное

Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются.

string

reasonобязательное

Машиночитаемая причина бизнес-отказа (например, input_expired, insufficient_balance). Ветвите обработку по ней, а не по тексту message.

string

error_codeобязательное

Тот же машинный код, что в reason, — второе имя поля. Значения всегда совпадают.

string

403

У ключа нет права voices.write

Разобрать этот ответ

Пример тела

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

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

404

Сервис Fish Audio закрыт для владельца ключа (service_not_found)

Разобрать этот ответ

Пример тела

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

Поля ответа

successобязательное

Всегда false у ошибок.

boolean

messageобязательное

string

reasonобязательное

string

error_codeобязательное

Тот же машинный код, что в reason, — второе имя поля. Значения всегда совпадают.

string

422

Под этим кодом два разных тела. Ошибка валидации: {success: false, message, errors: {поле: [текст]}} без reason (нет обязательного поля, нет согласия consent_biometric/consent_confirmed, language не двухбуквенный код ISO 639-1, образец не base64, больше 20 МБ или не WAV/MP3/M4A/AAC/OGG/WebM/FLAC). Потолок клонов тарифа: {success: false, message, reason: "voice_clone_quota_exceeded", error_code, max} — max это потолок; заархивируйте клон (DELETE) или перейдите на старший тариф. Различайте по наличию 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."
    ]
  }
}

Поля ответа

messageобязательное

Errors overview.

string

errorsобязательное

A detailed description of each field that failed validation.

object

*необязательное

произвольные ключи

array<string>

429

Превышен лимит частоты клонирования (rate_limit_exceeded): по умолчанию 6 попыток в минуту и 60 в сутки на пользователя, общий с веб-кабинетом и LumVoice; считается каждая попытка, в том числе отклонённая валидацией. Ждать retry_after секунд (заголовок Retry-After)

Разобрать этот ответ

Пример тела

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

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

reasonобязательное

Машиночитаемая причина отказа — по ней ветвите обработку, а не по тексту сообщения.

string

error_codeобязательное

Тот же машинный код, что в reason, — второе имя поля. Значения всегда совпадают; ветвитесь по любому из них.

string

retry_afterнеобязательное

Через сколько секунд имеет смысл повторить запрос (то же значение — в заголовке Retry-After).

может быть null

integer

Об этом словами

Realtime: подключение и подписка

Объекты

FishAudioVoiceClone

Соседние операции

Ещё

Скормить страницу ИИ

Открыть .md llm.md

спека 0.0.1

Тело запроса

Возможные ответы

Рядом

Скормить страницу ИИ