API завантаження й каверу в один крок

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

Опис кінцевої точки

Завантаження й кавер в один крок надсилає аудіофайл або URL аудіо та створює з цього вихідного аудіо нову версію каверу.

Кінцева точка: POST /api/music/upload-cover

Оплата: платно, наразі типово 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.

Якщо аудіо велике, «завантаження» й «кавер» краще розділити на два кроки (рекомендовано)

Ця кінцева точка вимагає покласти все аудіо в тіло запиту: чим більше аудіо, тим більше тіло, і одна заминка мережі чи тайм-аут обривають передавання на півдорозі, після чого сервер повертає unexpected end of JSON input (HTTP 400, без списання).

Коли аудіо перевищує приблизно 8 МБ, мережа нестабільна або той самий вихідний матеріал використовуватиметься кілька разів, переходьте на двоетапну форму:

1. POST /api/music/upload-source спершу завантажує вихідне аудіо — безкоштовно, можна повторювати будь-коли — і віддає clip_id;
2. POST /api/music/generate-from-source запускає кавер із цим clip_id — тіло платного кроку становить лише близько 250 байтів.

Див. API завантаження вихідного аудіо, API каверу з вихідного кліпу та «Великі файли й обрізані запити» в кінці цієї сторінки.

Параметри запиту

Headers

Параметри тіла

cover_start_s і cover_end_s задаються в секундах і можуть бути дробовими; час початку має бути меншим за час кінця й не перевищувати тривалість вихідного аудіо. Якщо обидва поля пропущено, використовується все аудіо. audio_weight відображається на metadata.control_sliders.audio_weight у Suno й керує тим, наскільки результат спирається на референсне аудіо; набуває значень 0.0-1.0 і може бути додане лише коли запит містить чинне референсне аудіо в file_url або file_base64. 0 є допустимим значенням; пропуск поля означає «не вказано» й зберігає типову поведінку Suno. instrumental і waitAudio мають бути логічними значеннями JSON, а не рядками.

Кінцева точка завантаження типово відповідає асинхронно. Поки clips[].status у відповіді дорівнює pending, порожній audio_url є нормальним і не означає, що завантаження чи кавер не вдалися; збережіть отриманий справжній song_id і опитуйте кінцеву точку пошуку пісень до завершення, перш ніж читати адресу аудіо.

Приклад запиту

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "Новий текст або напрям адаптації",
    "style": "Mandopop, acoustic guitar",
    "title": "Версія каверу",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Відповідь

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Версія каверу",
        "status": "pending"
      }
    ]
  }
}

Великі файли й обрізані запити

Рекомендовано: розділити завантаження й кавер на два кроки

Одноразова кінцева точка (ця) об'єднує завантаження й генерацію в один крок: велике тіло перебуває саме в цьому єдиному кроці, тож при обриві незрозуміло ні чи щось згенеровано, ні чи було списання.

Висновок: аудіо понад приблизно 8 МБ, нестабільна мережа або той самий матеріал кілька разів → двоетапна форма; крихітне аудіо в стабільній мережі → ця кінцева точка простіша.

Що означає 400 unexpected end of JSON input

Це означає, що JSON, який отримав сервер, неповний (це не помилка в параметрах, не проблема прав чи балансу). Типові причини, від найімовірнішої:

1. Велике тіло обрізане посеред передавання: вхідний шар фіксує і «скільки байтів заявив клієнт», і «скільки фактично надійшло». Виміряний випадок: клієнт заявив 14,17 МБ, а надійшло лише 11,8–12,4 МБ, і всі три запити зупинилися приблизно на 1,6–1,7 с; кількість відсутніх байтів щоразу була різною, що вказує на обрив передавання, а не на фіксовану межу (сервер не обмежує розмір тіла запиту).
2. Content-Length не збігається з фактично надісланими байтами: у Node.js використання .length рядка (кількість символів UTF-16) як довжини дає помилку, щойно вміст містить китайську або інший багатобайтовий текст.
3. Тіло записано рядком, а не Buffer, тому записані байти не збігаються з заявленими.

Усі три випадки трапляються до списання, тож витрат не виникає.

Самоперевірка на боці клієнта

• Content-Length беруть із Buffer.byteLength(json, 'utf8') (або Buffer.from(json).length) — ніколи з json.length;
• Тіло запиту записують як Buffer, а не як рядок;
• Тайм-аут сокета / запиту ≥ 300 секунд;
• Якщо аудіо понад приблизно 8 МБ: використайте file_url (тіло лише кілька сотень байтів), або multipart-завантаження з upload-source, або одразу двоетапну форму;
• У multipart-запитах не задавайте Content-Type вручну (boundary має додати клієнт);
• Виведіть «скільки байтів фактично надіслано» й порівняйте з Content-Length;
• У двоетапній формі переконайтеся, що крок 1 повернув clip_id і status у завершеному стані, перш ніж надсилати крок 2.

Поширені помилки

Пов'язані кінцеві точки: API завантаження вихідного аудіо (крок 1), API каверу з вихідного кліпу (крок 2).