API клонирования голоса и генерации с заданным голосом (не рекомендуется)

Обновлено 2026-09-18 · команда Suno-API

⛔ Старая цепочка, не рекомендуется для новых интеграций. Эта страница описывает раннюю цепочку persona (voice_task_id / generate-with-voice). Она по-прежнему работает, но клиентам больше не рекомендуется; в навигации слева она помечена как «не рекомендуется».

Для новых интеграций используйте 【Рекомендуется】 API голосового профиля: создайте голосовой профиль из одного образца голоса (POST /api/music/voice-profile/create), а затем применяйте его, чтобы сделать кавер на выбранную песню или спеть новую. Голосовой профиль — полноценный ресурс: его можно перечислить, запросить и удалить, а исходное аудио сохраняется навсегда.

Если вашему продукту нужен полный цикл «создать голос → долго переиспользовать → делать каверы», выбирайте новую цепочку.

Важно: клонированный голос может истечь.

voice_id / voice_task_id, созданные клонированием голоса, — не вечный ресурс: они могут перестать работать из-за срока действия, состояния аккаунта или изменения состояния голоса. Интегратор не должен один раз клонировать голос и затем вечно переиспользовать сохранённый локально идентификатор.

Рекомендуемая практика:

• Храните voice_task_id, voice_id, is_available, updated_at и время последней успешной генерации.
• Перед каждой генерацией с клонированным голосом вызывайте GET /api/voice/clone/tasks/{voice_task_id} или POST /api/voice/clone/tasks/{voice_task_id}/check и убеждайтесь, что is_available=true.
• Если эндпоинт сообщает, что голос недоступен, задача не существует или возвращает selected voice is not ready, предложите пользователю клонировать заново или выбрать другой доступный голос.
• Не обещайте конечным пользователям, что клонированный голос — «вечный актив»; покажите в интерфейсе продукта, что «голос может истечь и потребовать повторной проверки или повторного клонирования».

Описание эндпоинта

Эта группа эндпоинтов создаёт переиспользуемый голос и генерирует с ним песни. Вызывающей стороне нужен только API Key, выданный платформой; сервер сам отвечает за постановку задач, синхронизацию статусов, биллинг и скачивание.

Аутентификация: Authorization: Bearer YOUR_API_KEY

Оплата:

• Проверка голоса, клонирование голоса, запрос статуса, удаление и скачивание: бесплатно.
• Вход в одношаговое клонирование в рабочем пространстве: фиксированные 5 ¥ за вызов; он автоматически выполняет проверку исходного голоса и второе проверочное аудио, а при неудаче возвращает деньги.
• Автоматическое продолжение на проверочное аудио после обычного клонирования: фиксированные 5 ¥ за вызов; при неудаче возврат по текущему порядку.
• Генерация песни клонированным голосом: платно, фиксированные 1,2 ¥ за вызов; обычно каждый вызов возвращает 2 задачи-заполнителя.
• При включённом Max Mode (max_mode: true в POST /api/music/generate-with-voice) эти 1,2 ¥ за вызов считаются по двойному тарифу, то есть 2,4 ¥ за вызов; генерация голосом также поддерживает variety (0-4, без доплаты) — правила значений в разделе «Расширенные параметры» обзора нового API.

Порядок вызовов

1. Вызовите POST /api/voice/clone/validate, чтобы загрузить исходный голос и получить voice_task_id.
2. Дождитесь или опрашивайте GET /api/voice/clone/tasks/{voice_task_id}, пока не получите validate_info.
3. Пользователь читает этот текст вслух и записывает проверочное аудио.
4. Вызовите POST /api/voice/clone/tasks/{voice_task_id}/generate, чтобы отправить проверочное аудио.
5. Вызывайте POST /api/voice/clone/tasks/{voice_task_id}/check или продолжайте опрашивать задачу, пока не получите is_available=true.
6. Вызовите POST /api/music/generate-with-voice, чтобы сгенерировать песню этим голосом.
7. Эндпоинт генерации сначала возвращает задачи-заполнители; когда генерация завершится и у вас появится настоящий song_id, эндпоинты скачивания позволят получить один файл или архив.
8. (Необязательно) Когда голос больше не нужен, вызовите DELETE /api/voice/clone/voices/{voice_task_id}, чтобы удалить его; семантика — в разделе 6.

Есть также одношаговое клонирование: на первой странице записи/загрузки исходного голоса в рабочем пространстве можно выбрать завершение в один шаг — система выполнит проверку и создание голоса сразу, так что второе проверочное аудио записывать не придётся; стоит 5 ¥ за вызов, при неудаче деньги возвращаются.

Поля задачи голоса

1. Отправить исходный голос на проверку

Эндпоинт: POST /api/voice/clone/validate

Параметры тела

vocal_end_s - vocal_start_s должно удовлетворять минимальному требованию к вокальному фрагменту. Загружайте чистую запись вокала без заметного сопровождения и шума.

Пример запроса

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Мой китайский женский голос",
    "description": "Чистый и естественный китайский женский голос",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Пример ответа

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Мой китайский женский голос",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Запросить задачу голоса

Эндпоинт: GET /api/voice/clone/tasks/{voice_task_id}

Пример запроса

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример ответа

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Мой китайский женский голос",
      "validate_info": "Прочитайте вслух текст проверки, возвращённый здесь",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Пересоздать текст проверки

Эндпоинт: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Вызывайте, когда текст проверки неудобно читать вслух или нужно пройти проверку заново.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Отправить проверочное аудио и создать голос

Эндпоинт: POST /api/voice/clone/tasks/{voice_task_id}/generate

Параметры тела

Пример запроса

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Мой китайский женский голос"
  }'

5. Проверить, доступен ли голос

Эндпоинт: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Когда задача доступна, is_available в ответе равен true и возвращается voice_id.

6. Удалить голос

Эндпоинт: DELETE /api/voice/clone/voices/{voice_task_id}

Оплата: бесплатно.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример ответа

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Что происходит после удаления

• Голос больше нельзя использовать для новых песен: вызов POST /api/music/generate-with-voice с этим voice_task_id (или его voice_id) отклоняется с сообщением selected voice is not ready, списания нет.
• Песни, уже созданные этим голосом, вообще не затронуты: воспроизведение, скачивание, продолжение, замена и разделение дорожек работают как раньше.
• Задача голоса исчезает из запросов: GET /api/voice/clone/tasks/{voice_task_id} возвращает record not found.
• Исходное аудио сохраняется согласно политике бессрочного хранения платформы (с 2026-09-23 удаление больше не очищает загруженный образец голоса), но это не значит, что его можно восстановить: старая задача завершена, и чтобы продолжать тем же голосом, нужно пройти цепочку клонирования заново — вы получите новый voice_task_id.
• Повторное удаление: удаление той же задачи ещё раз возвращает record not found (она уже удалена и не находится).

7. Генерация песни клонированным голосом

Эндпоинт: POST /api/music/generate-with-voice

Оплата: 1,2 ¥ за вызов.

Параметры тела

Поддерживаются suno-v6, suno-v6-wild и suno-v6-mini; пустое значение модели трактуется как suno-v6. Старые модели V5/V5.5 выведены, но в исторических задачах могут остаться старые имена моделей.

Общая структура запроса также разбирает поля совместимости Create UI: task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId, voiceId, но они не являются допустимыми клиентскими параметрами этого эндпоинта: задача голоса должна передаваться как voice_task_id, необязательная проверка голоса — как voice_id, а генерация музыки голосом никогда не читает поля sound.

Как заполнять параметры генерации

• При customMode=false в prompt передаётся описание песни; при customMode=true в prompt передаётся полный текст песни, а также обязательно заполняются style и title. Не отправляйте текст песни в поле описания режима вдохновения и не считайте описание песни текстом песни расширенного режима.
• weirdnessConstraint и styleWeight — это десятичные доли от 0.0 до 1.0; нельзя передавать 50 или 50%. 0.5 — сбалансированное значение; пропуск означает «не задано», а 0 — допустимое явное значение.
• vocalGender принимает только m, male, f или female. instrumental здесь лишь поле совместимости: генерация клонированным голосом всегда считается вокальной песней.
• waitAudio здесь ничего не меняет; эндпоинт всегда асинхронно возвращает задачи-заполнители. Пустой audio_url в первом результате — норма: опрашивайте по client_request_id и читайте адрес аудио только после завершения результата.

Параметры заголовков

Поведение Idempotency-Key:

• Первый запрос до списания записывает постоянную запись идемпотентности;
• Если тот же ключ с тем же запросом уже завершён, повторяется первый ответ о приёме, без повторного списания и создания задачи;
• Тот же ключ с другим телом запроса отклоняется;
• Тот же ключ, ещё находящийся в обработке, даёт стабильную ошибку обработки и отдаёт безопасный client_request_id только когда он уже создан;
• Если первый запрос с этим ключом завершился неудачей, состояние неудачи сохраняется; для повтора нужен новый ключ.

Условия кавера через sourceClipId

Кавер из источника в клиентском API полностью обрабатывается на сервере: доступ к песне-источнику решает сервер, и клиент не передаёт данные аккаунта. Возможность определяется фактическим ответом эндпоинта.

Источник должен принадлежать текущему пользователю API, быть завершённой песней рабочего пространства, не pending:, и иметь доступное аудио. Поддерживаются обычная генерация, источники обычной загрузки и финальная песня усиленной загрузки; промежуточные записи усиленной загрузки отклоняются до списания. Сервер принимает только переданный клиентом id песни-источника и никогда не принимает id аккаунта; недоступный или незавершённый источник даёт ошибку до списания.

Пример запроса

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Напиши китайскую поп-песню о морском береге летней ночью",
    "style": "Mandopop, warm piano, emotional",
    "title": "Морской бриз летней ночью",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Пример ответа

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Морской бриз летней ночью",
        "prompt": "Напиши китайскую поп-песню о морском береге летней ночью"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Морской бриз летней ночью",
        "prompt": "Напиши китайскую поп-песню о морском береге летней ночью"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

О задачах-заполнителях и итоговом song_id

generate-with-voice — асинхронный эндпоинт генерации. Успешный ответ означает лишь, что задача генерации отправлена, а не что песня готова.

Смысл ключевых полей ответа:

Внимание: placeholder_id, начинающийся с pending:, нельзя использовать как итоговый song_id и нельзя передавать в /api/music/query или эндпоинты скачивания. Если вызвать /api/music/query только со значениями pending:*, может вернуться пустой массив [], потому что настоящая песня ещё не готова или задача-заполнитель ещё не заменена итоговым id песни.

Неверный пример:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Правильный порядок:

1. Вызовите POST /api/music/generate-with-voice, чтобы отправить задачу генерации голосом.
2. Сохраните client_request_id, items[].placeholder_id и items[].client_request_index из ответа.
3. Опрашивайте GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Когда items[].song_id получит значение, не начинающееся с pending:, вызывайте /api/music/query, /api/music/download-file или /api/music/download-all.

Текущая версия добавляет публичный эндпоинт запроса:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Он возвращает результаты задач с тем же client_request_id у текущего пользователя, чтобы клиент сам мог узнать итоговый song_id. В возвращаемом списке:

• song_id — настоящий id песни;
• placeholder_id появляется только пока задача находится в состоянии заполнителя;
• значение, начинающееся с pending:, нельзя использовать с /api/music/query или эндпоинтами скачивания.

Если вы сохранили только client_request_id или заполнитель pending:*, сначала вызовите этот эндпоинт результатов; если настоящий song_id всё ещё не найден, передайте client_request_id в техподдержку для локализации.

Запрос результатов генерации голосом

Эндпоинт: GET /api/music/generate-with-voice/results

Оплата: бесплатно.

Параметры запроса

Пример запроса

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример ответа во время генерации

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Морской бриз летней ночью"
      }
    ]
  }
}

Пример ответа после завершения

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Морской бриз летней ночью",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Значения верхнеуровневого status

8. Скачать один файл

Эндпоинт: POST /api/music/download-file

Параметры тела

Пример запроса

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Ответ — поток файла; Content-Type и имя файла соответствуют тому, что возвращает бэкенд.

9. Скачать ресурсы песни архивом

Эндпоинт: POST /api/music/download-all

Параметры тела

Пример запроса

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Архив обычно содержит аудио, обложку и metadata.json; если какой-то тип ресурса ещё не создан, он не попадает в архив.

Частые ошибки

Ошибки этой группы всегда возвращают HTTP 200: определяйте результат по полю success в теле ответа (false — неудача, причина в message), а не только по коду состояния HTTP. Полная семантика удаления голоса (можно ли им пользоваться дальше, можно ли восстановить) — в разделе 6.