API запиту пісень та історії

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

Ця сторінка охоплює три безкоштовні кінцеві точки запиту:

Якщо ви використали на кінцевій точці генерації режим квитанції-приймання (accept_mode=async), у вас на руках номер квитанції, а не ID пісні. Відстежуйте поступ через GET /api/music/requests/{request_id} і поверніться до кінцевих точок цієї сторінки, коли отримаєте справжній song_id. Див. «Режим квитанції-приймання» в API генерації в простому режимі.

Автентифікація та обсяг даних

Усі три кінцеві точки використовують той самий ключ API:

Authorization: Bearer YOUR_API_KEY

Історія пісень ізольована за user_id, якому належить ключ API. Кілька ключів, створених під одним головним акаунтом, можуть читати історію цього акаунта, але не пісні іншого користувача чи акаунта підсайту.

Кінцеві точки історії повертають лише справді згенеровані пісні. Виключено:

• записи-заповнювачі генерації, що починаються з pending:;
• завантаження вихідного аудіо та записи вдосконаленого завантаження;
• побічні результати, як-от розділення вокалу й акомпанементу та стеми;
• пісні інших користувачів або акаунтів підсайтів.

1. Запит стану генерації

Шукає поточний стан і кінцевий результат для одного або кількох ID пісень.

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

Оплата: безкоштовно.

Headers

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

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

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

Приклад відповіді

[
  {
    "song_id": "clip_id_1",
    "song_title": "Назва пісні",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Текст пісні",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

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

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

song_ids має містити справжні ID пісень. Заповнювач, що починається з pending:, не є кінцевим song_id і тут не працює; запит лише за заповнювачами може повернути порожній масив [].

model, model_version або платформний model_name у відповіді можуть зберігати історичні значення. Нові завдання мають використовувати suno-v6, suno-v6-wild або suno-v6-mini; від suno-v2 до suno-v5-5 виведено з ужитку, і поява цих назв в історії не означає, що модель ще можна надсилати.

Поки завдання в стані pending, submitted або processing, поля audio_url, video_url і cover_url можуть бути порожніми — це нормально для незавершеного завдання. Не робіть висновок про збій лише з порожньої адреси; орієнтуйтеся на status і запитайте знову, коли стан завершено. Лише якщо стан завершено, а адреси досі порожні, варто звернутися до підтримки, вказавши song_id.

⚠️ Адреси аудіо живуть 7 днів — перенесіть файли вчасно

audio_url, video_url (та інші адреси медіа, наприклад WAV), які повертає ця кінцева точка, віддаються з об'єктного сховища платформи і типово спливають через 7 днів: файли переробляються, а стара адреса повертає 404.

• Протягом цих 7 днів перенесіть файли у власне сховище; не вважайте адресу довготривалим посиланням.
• Протермінована адреса не потребує повторної генерації пісні й не оплачується знову: викличте цю кінцеву точку (POST /api/music/query) ще раз, щоб отримати свіжу дійсну адресу цієї пісні.

2. Запит історії пісень акаунта

Перелічує пісні, створені головним акаунтом поточного ключа API. Підходить для власного списку пісень, вибору або сторінки історії.

Кінцева точка: GET /api/music/songs

Оплата: безкоштовно.

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

Результати впорядковано за created_at і внутрішнім ID запису за спаданням, тож порядок сторінок стабільний.

Як знайти надсилання, що вийшло за тайм-аут: кінцеві точки генерації не дають проміжної відповіді до приймання. Якщо клієнт вийшов за тайм-аут або з'єднання обірвалося під час надсилання, замовлення могло вже бути прийняте й генеруватися. Погляньте на цю кінцеву точку (найновіші спершу): прийняті пісні з'являються у списку як звичайно. Надсилайте повторно лише після підтвердження, що її справді немає, аби не заплатити двічі. Див. «Час очікування та налаштування тайм-ауту» в Огляді нового API.

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

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Приклад відповіді

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Місто вночі",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Поля відповіді

Кінцева точка списку не повертає промпти, поля оплати, інформацію про акаунт чи сирі відповіді. Для промптів і параметрів генерації викличте кінцеву точку деталей пісні.

3. Запит параметрів генерації

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

Кінцева точка: GET /api/music/songs/:song_id

Оплата: безкоштовно.

Читати можна лише пісні головного акаунта, якому належить поточний ключ API. Пісні інших користувачів або акаунтів підсайтів однаково трактуються як «пісню не знайдено».

Параметр шляху

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

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Приклад відповіді

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Місто вночі",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "міські вулиці після дощу, текст про нову зустріч",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Місто вночі",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

Поля parameters

Поле prompt_view (перегляд промпту, додано 2026-09-28)

prompt_view — нормалізована структура, призначена для «перегляду промпту»: вона впорядковує дані у фіксовані розділи за типом генерації, тож клієнтові більше не потрібно вирішувати, яке поле показувати. Це суто додаткове поле — старі поля (parameters, parameter_retention) зберігають назву та значення, а клієнти, які не розбирають нове поле, взагалі не зазнають впливу.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Розширений режим",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Четверта ранку#701f37", "title_base": "Четверта ранку", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "електроніка ґочао, глибокий саб-бас, ретро-синтезатор",
    "style_tags": "електроніка ґочао, глибокий саб-бас, ретро-синтезатор",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Поля, що можуть з'явитися в extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, а також група звукових ефектів sound_type / sound_bpm / sound_key / sound_loop. Порожні значення ніколи не повертаються.

Три правила відображення (дотримуйтеся їх, а не здогадуйтеся):

1. Розрізняйте джерело стилю: за style_source=suno_derived показуйте «стиль (виведено Suno з вашого опису)» і ніколи «ваш стиль»;
2. Внутрішні промпти ніколи не з'являються: голосові кавер-типи повертають лише 【вимоги до стилю】/【вимоги до каверу】, які ввів користувач; фіксована конструкція, яку ми складаємо для моделі, не з'являється в жодному полі (історичні дані очищено так само);
3. Не вгадуйте відсутні параметри: якщо чогось немає в extended, тоді це не записали — поясніть причину через retention.

Примітки щодо збереження параметрів

parameter_retention розділяє «порожнє значення передано явно» та «поле історично не зберігалося»:

• core_parameters_available: чи існує головний запис завдання; у коректному запиті деталей зазвичай true;
• extended_parameters_available: чи знайдено пов'язаний запис розширеного музичного завдання;
• sources: з яких таблиць даних узято цю відповідь;
• unavailable_fields: поля, які не можна надійно відновити з історії; вони повертають null у parameters.

Звичайні історичні пісні зазвичай зберігали промпт, стиль, поточну назву, модель, тип генерації та вихідну пісню, але не зберігали окремо всі розширені параметри. Платформа ніколи не вгадує відсутні значення з generation_type.

Деякі розширені музичні завдання також зберегли початковий промпт, стиль, назву, модель, а також custom_mode, negative_tags, vocal_gender, style_weight і weirdness_constraint. Навіть коли розширений запис існує, instrumental, lyrics_mode і wait_audio можуть залишитися невідновними.

Назви пісень користувач може змінити пізніше. Коли звичайне історичне завдання не зберегло окремої початкової назви, parameters.title може бути поточною назвою; коли є запис розширеного завдання, перевага надається початковій назві генерації, збереженій там.

Не знайдено або немає прав

Бізнес-помилки використовують єдиний конверт відповіді. Коли пісні немає або вона не належить поточному акаунту:

{
  "success": false,
  "message": "song not found"
}

Ця бізнес-помилка зараз повертається з HTTP 200, тож оцінюйте результат за полем success. Відсутній, недійсний, протермінований або вимкнений ключ API повертає HTTP 401.

Примітки щодо безпеки

Кінцеві точки історії та деталей ніколи не повертають:

• ключі API або ID токенів;
• поля квот, оплати чи повернень;
• інформацію про акаунт або сирі відповіді;
• внутрішні ключі об'єктного сховища;
• помилки адміністратора чи помилки внутрішніх ресурсів.