API розділення на доріжки (вокал і супровід)

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

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

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

1. Якщо вихідне аудіо — не пісня, створена на цій платформі, спершу викличте API завантаження вихідного аудіо.
2. Викличте POST /api/music/separate, щоб надіслати завдання розділення.
3. Опитуйте результат через API запиту пісень та історії.
4. Завантажте аудіофайл кожного результату розділення кінцевими точками завантаження.

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

Оплата: платно. stem_mode=two наразі типово 0,6 ¥ за виклик; stem_mode=twelve — багатодорожечне розділення, наразі типово 3,0 ¥ за виклик. Фактично списана сума відповідає поточній конфігурації цін у бек-офісі.

Час очікування та тайм-аути (важливо): це синхронна кінцева точка — замовлення приймають і передають у генерацію лише коли надходить відповідь. За вимірами більшість запитів відповідають за 1-3 секунди, близько 10% тривають понад 30 секунд, а найдовший — близько 230 секунд. Установіть тайм-аут клієнта 300 секунд або більше; відсутність відповіді не означає, що нічого не згенеровано, і не повторюйте запит одразу після тайм-ауту (це дублює замовлення й списує кошти вдруге). Якщо з'єднання обірвалося, перевірте пізніше через GET /api/music/songs. Див. «Час очікування та налаштування тайм-ауту» в Огляді нового API.

Автентифікація

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

Про stem_mode

Про розділення

Розділення — це незалежна фіксована можливість: модель генерації пісень вказувати чи обирати не потрібно. Клієнт лише надсилає вихідну пісню та stem_mode; сервер обробляє відповідно до режиму.

Звідки беруться числа: одне надсилання створює 2 версії (два результати з одного матеріалу), тож кількість = 2 × кількість доріжок цього режиму: 4 для two і 24 для twelve. Завжди орієнтуйтеся на фактичну довжину масиву clips у відповіді; не пишіть цикл за фіксованою кількістю (окремі доріжки можуть не вдатися, а успішні повертаються як звичайно).

Які доріжки повертає кожен режим

12 доріжок режиму twelve (назви задає платформа; порядок може змінюватися):

Режим two повертає дві доріжки, (Vocals) та (Instrumental), кожну у 2 версіях. Назви доріжок у two і twelve — фіксовані імена (без назви вихідної пісні), тож не сподівайтеся визначити за назвою, з якої пісні доріжка.

Назви доріжок не можна використовувати як унікальний ключ. У двох версіях трапляються доріжки з однаковою назвою (наприклад дві (Vocals), дві (Strings)), і одне розділення повертає багато доріжок. Завжди використовуйте song_id як ідентифікатор, а song_title — лише для показу; не використовуйте й індекси масиву (порядок може змінюватися).

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

Розділення вокалу / супроводу (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

Багатодорожечне розділення (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

Відповідь

У разі успіху зазвичай повертається масив результатів розділення. Кожен результат — окремий кліп пісні, який потрібно далі опитувати, доки status не стане завершеним.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

Вище показано лише 2 із 4 записів режиму two; насправді повертається 4 (2 версії × {(Vocals), (Instrumental)}); режим twelve повертає 24. Реальна кількість — довжина масиву clips.

Зазвичай клієнту достатньо зберегти clips[].song_id; подальші запити й завантаження обертаються навколо цих ID.

Примітки

• Результати розділення не з'являються в історії GET /api/music/songs (цей список повертає лише звичайно згенеровані пісні). Після успішного надсилання негайно збережіть clips[].song_id, інакше потім їх не знайти.
• Кожна доріжка — самостійний твір: у кожної свій song_id, її треба окремо опитувати до завершення й окремо завантажувати.
• Оплата не залежить від кількості записів: вона за виклик (two 0,6 ¥ за виклик, twelve 3,0 ¥ за виклик), і 4 чи 24 записи коштують однаково.
• Завантаження: використайте song_id цієї доріжки з POST /api/music/download-url / download-file (безкоштовно) або одразу audio_url з результату запиту; про MIDI див. API отримання MIDI.
• Не надсилайте двічі: розділення — синхронна кінцева точка, тож після тайм-ауту спершу перевірте запитом пісень, а не повторюйте одразу (це дублює замовлення й списує кошти вдруге).
• Непотрібні доріжки приховуйте через API видалення стемів.

Запит результатів розділення

Після успішного надсилання запитайте результати з clips[].song_id через POST /api/music/query.

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

Приклад завершеного запиту:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

Завантаження файлів доріжок

Коли результат розділення завершено, окремий файл доріжки можна завантажити кінцевою точкою завантаження.

Кінцева точка: 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": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind підтримує:

Щоб завантажити пов'язані ресурси одного результату розділення пакетом, викличте:

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": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

Опис статусів

Часті помилки

Примітки щодо сумісності

У старій документації використовувалися приклади з одним об'єктом, як-от success/task_id/vocals_url/instrumental_url. Поточне розділення працює з масивом пісень clips[]: кожен результат має власний song_id, і подальші запити та завантаження обертаються навколо цих song_id.

Пов'язані сторінки

• Якщо потрібно лише відокремити вокал від супроводу без вибору режиму, скористайтеся API видалення вокалу; це швидка дводорожечна форма цієї кінцевої точки, і наразі вона безкоштовна.
• Непотрібні доріжки розділення приховуйте через API видалення стемів (логічне видалення, без списань).
• MIDI доріжки — API отримання MIDI; аудіо, обкладинка та інші медіа — API завантаження та попереднього прослуховування медіа пісні.