API кавера по исходному клипу

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

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

Кавер по исходному клипу переиспользует исходный клип, который вы уже загрузили или который уже существует, и создаёт на его основе новую версию кавера.

Эндпоинт: POST /api/music/generate-from-source

Оплата: платно, сейчас по умолчанию 0,6 ¥ за вызов. Загрузка исходного аудио сама по себе бесплатна; списание происходит при создании кавера по исходному клипу. Фактически списанная сумма следует текущей конфигурации цен в бэк-офисе.

Max Mode / Variety: эндпоинт поддерживает необязательные параметры max_mode и variety (0-4). При включённом max_mode этот вызов тарифицируется по двойной цене (0,6 → 1,2 ¥ за вызов); variety не стоит ничего дополнительно. Что они означают и как их отправлять — в разделе «Расширенные параметры» Обзора нового API.

Время ожидания и тайм-ауты (важно): это синхронный эндпоинт — заказ принимается и передаётся в генерацию только при получении ответа. По измерениям большинство запросов отвечают за 1-3 секунды, около 10% занимают больше 30 секунд, а самый долгий — около 230 секунд. Установите тайм-аут клиента 300 секунд или больше; отсутствие ответа не означает, что ничего не сгенерировано, и не повторяйте запрос сразу после тайм-аута (это дублирует заказ и списывает деньги повторно). Если соединение оборвалось, проверьте позже через GET /api/music/songs. См. «Время ожидания и настройка тайм-аута» в Обзоре нового API.

Рекомендуемое использование: это шаг 2 «двухшагового кавера». На шаге 1 загрузите файл через API загрузки исходного аудио (бесплатно) и сохраните clip_id; на шаге 2 вызовите этот эндпоинт, чтобы запустить кавер. Так аудио появляется только на бесплатном шаге: если загрузка не удалась, просто повторите её — деньги не списываются, а тело запроса платного шага занимает всего несколько сотен байт, поэтому оно вряд ли сорвётся из-за обрыва передачи. API загрузки и кавера в один шаг кладёт в тело запроса всё аудио целиком, поэтому как только аудио превышает примерно 8 МБ, оно легко обрезается в пути и возвращает unexpected end of JSON input (см. «Большие файлы и обрезанные запросы» на той странице).

Кроме того, один и тот же clip_id можно переиспользовать для Extend, Replace Section, разделения на дорожки и других последующих действий — повторно загружать аудио не нужно.

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

Headers

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

weirdnessConstraint, styleWeight и audio_weight принимают десятичную долю от 0.0 до 1.0, а не целое число процентов; например, 50% записывается как 0.5. 0 — допустимое значение; «не указано» означает только пропуск поля. audio_weight отображается на metadata.control_sliders.audio_weight в Suno и управляет тем, насколько результат опирается на референсное аудио; его можно передавать только когда в запросе есть действующий sourceClipId или референсное аудио, поэтому не отправляйте его при обычной генерации только по тексту. При customMode=true напишите новый текст в prompt и укажите одновременно style и title; при customMode=false напишите в prompt творческое описание. instrumental и waitAudio должны использовать логические значения JSON true/false.

Этот эндпоинт по умолчанию отвечает асинхронно. Пока возвращённый status равен pending, пустой audio_url — это нормально; дождитесь завершения, прежде чем использовать адрес аудио. sourceClipId должен быть реальным ID исходной песни/клипа — нельзя использовать task_id, client_request_id или заполнитель с pending:.

Что за ID такой sourceClipId

sourceClipId — это реальный идентификатор клипа Suno, используемого как источник этого кавера. Клиентский объект песни на платформе обычно называет этот идентификатор song_id, а параметры запроса кавера сохраняют имя sourceClipId; здесь оба означают один и тот же реальный ID песни.

Если источник — усиленная загрузка, сначала запросите задачу усиленной загрузки и дождитесь, пока status станет completed, а затем подставьте возвращённый реальный song_id в sourceClipId. Рекомендуется также подставить audio_url и title этого результата в sourceAudioUrl и sourceTitle.

Не подставляйте в sourceClipId ни task_id, ни client_request_id, ни заполнитель pending:enhanced-upload:* от усиленной загрузки.

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

curl -X POST https://www.suno-api.io/api/music/generate-from-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "sourceClipId": "uploaded_or_existing_clip_id",
    "sourceAudioUrl": "https://example.com/source.mp3",
    "sourceTitle": "Название исходного аудио",
    "prompt": "Новый текст или творческое направление",
    "customMode": true,
    "style": "Mandopop, warm vocal",
    "title": "Название кавера",
    "negativeTags": "noise",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false
  }'

Ответ

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Название кавера",
        "status": "pending"
      }
    ],
    "source_update": {}
  }
}

Примечания

Этот эндпоинт по возможности разбирается с тем, какому аккаунту принадлежит исходный клип. Если исходный клип нельзя использовать напрямую, сервер может повторно загрузить его на основе информации об исходном аудио и только затем сгенерировать результат.