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

Примітки

Ця кінцева точка намагається розв'язати питання того, якому акаунту належить вихідний кліп. Якщо вихідний кліп не можна використати напряму, сервер може повторно завантажити його на основі інформації про вихідне аудіо і вже потім згенерувати результат.