Огляд документації Suno API

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

Зареєструйтеся за адресою електронної пошти — і зможете створити ключ API. Одна генерація коштує 0,6 ¥, повертає 2 пісні та охоплює завантаження MP3/WAV, кавер-пісні, Extend, стеми й клонування голосу. Базова URL-адреса: https://www.suno-api.io.

На цій сторінці зібрано доступні нині моделі, усі кінцеві точки генерації й редагування, принцип оплати та рекомендований порядок читання. Якщо ви інтегруєте вперше, читайте згори вниз; розділи про помилки 401/403/429 теж тут.

Короткі відповіді

Як отримати ключ API? Зареєструйтеся за адресою електронної пошти, відкрийте консоль, перейдіть до керування токенами та створіть токен. Номер телефону й банківська картка не потрібні.

Скільки коштує один виклик? Одна генерація коштує 0,6 ¥ і повертає 2 пісні. Запити стану, WAV, текст із часовими мітками та підказки промптів безкоштовні.

Які моделі підтримуються? suno-v6 (типова), suno-v6-wild і suno-v6-mini. Стандартні моделі генерації v5.5 і старші виведено з ужитку; на наявні роботи це не впливає.

Яка базова URL-адреса? https://www.suno-api.io, із заголовком Authorization: Bearer YOUR_API_KEY.

Доступні нині моделі

Клієнтські моделі для стандартної генерації пісень — це suno-v6, suno-v6-wild і suno-v6-mini. Якщо model не вказано, використовується suno-v6.

Стандартні моделі suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 і suno-v5-5 виведено з ужитку. У старих завданнях ці назви ще можуть показуватися; це історичні дані, а не ознака того, що модель можна використовувати для нових запитів. Виняток — стеми: див. API розділення на стеми (вокал/музика).

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

Кожна публічна кінцева точка з ключем API використовує однаковий набір заголовків:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Базова URL-адреса:

https://www.suno-api.io

Загальні правила щодо параметрів

• Значення number у тілі запиту має бути числом JSON, а не рядком із відсотками. Інтенсивність 50% записують як 0.5, ніколи як 50 чи 50%.
• Значення boolean має бути true або false. Не надсилайте замість них 0 чи 1.
• Поля, позначені "ні", можна не надсилати взагалі. Якщо не впевнені, що робить параметр, опустіть його, щоб сервіс використав типову поведінку; не надсилайте порожній рядок, null чи 0 замість "не надіслано", бо 0 є припустимим значенням для частини числових полів.
• Назви полів чутливі до написання. Кожна сторінка кінцевої точки перелічує рекомендовану назву та сумісні псевдоніми; надсилайте точно так, як показано в таблиці параметрів. Там, де документація каже, що приймаються і snake_case, і camelCase, не надсилайте обидва одночасно.
• Кожне поле тривалості, що закінчується на _s або Seconds, вимірюється в секундах і приймає десяткові значення. Позначки часу Unix описано окремо, зокрема те, у секундах вони чи в мілісекундах.
• Ідентифікатор, що починається з pending:, — це тимчасовий заповнювач платформи, а не справжній song_id. Використовуйте його лише там, де кінцева точка явно документує підтримку заповнювачів; інакше дочекайтеся справжнього song_id.

Обмеження текстових полів

Перевищення текстового ліміту повертає одразу HTTP 400: нічого не генерується, кошти не списуються наперед і запис завдання не створюється. Лічба ведеться в символах Unicode (один ієрогліф китайської рахується як 1), а пробіли на початку й у кінці також рахуються.

Поле message називає поле-порушник і виміряну довжину, тож цих двох чисел достатньо, щоб скоротити текст:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Стосується: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Один виняток: поле description у POST /api/music/sounds обмежене 100 символами, бо шлях звукових ефектів використовує коротший ліміт платформи.

Асинхронна генерація та адреси аудіо

Кінцеві точки генерації музики типово працюють асинхронно. Коли перша відповідь містить status зі значенням pending, submitted або processing, порожні audio_url, video_url чи cover_url — це нормально і не означає, що завдання не вдалося. Збережіть справжній song_id (або client_request_id, який повернула кінцева точка) і викликайте відповідну кінцеву точку запиту; читайте й завантажуйте адресу аудіо лише коли стан завершено.

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

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

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

Час очікування та налаштування тайм-ауту

Кінцеві точки генерації синхронні: замовлення приймають і передають платформі на генерацію лише тоді, коли надходить відповідь. До того сервіс має підібрати акаунт і пройти обов'язкову перевірку безпеки, і жодної проміжної відповіді немає — жодна інша кінцева точка теж не бачить цього замовлення. Тож єдиний надійний доказ, що "щось згенеровано", — це сама відповідь, а не те, що ви спостерігаєте під час очікування.

Виміряний час очікування (сімейство /api/music/create у продакшені, 2026-09-18 — 2026-09-20)

• Близько 10% запитів тривають понад 30 секунд, а близько 1% — від 1 до 2 хвилин. Повільний запит зазвичай означає, що саме цьому довелося спершу пройти перевірку безпеки.
• Поля запиту, форма відповіді, коди помилок і оплата не змінилися, тож наявним інтеграціям потрібно лише збільшити тайм-аут клієнта — без жодних інших змін у коді.

Вимоги до інтеграції

1. Встановіть тайм-аут клієнта 300 секунд або більше. Клієнти з типовими 30, 60 чи 120 секундами розірвуть з'єднання під час очікування.
2. Відсутність відповіді не означає, що нічого не згенеровано. Під час тайм-ауту чи обриву з'єднання замовлення могло вже бути прийняте й генеруватися.
3. Не повторюйте запит одразу після тайм-ауту: повторне надсилання створює друге замовлення і списує кошти ще раз.
4. Якщо з'єднання обірвалося, трохи згодом перелічіть свої пісні через GET /api/music/songs (найновіші спершу) — прийняті замовлення з'являться як завжди. Надсилайте повторно лише тоді, коли переконалися, що замовлення справді немає.
5. Повідомляючи про проблему, долучіть заголовок відповіді X-Oneapi-Request-Id, щоб цей запит можна було знайти одразу.

Не хочете тримати довге з'єднання? Скористайтеся режимом квитанції-приймання. POST /api/music/create і POST /api/music/create/custom підтримують необов'язкову квитанцію приймання: додайте "accept_mode": "async" у тіло (або заголовок X-Accept-Mode: async), і кінцева точка одразу поверне 202 разом із номером квитанції, поки генерація триває у фоні; відстежуйте поступ через GET /api/music/requests/{request_id}. Клієнт із тайм-аутом лише в кілька десятків секунд тоді не сплутає "немає відповіді" з "нічого не згенеровано" і не отримає подвійного списання через повтори. Див. "Режим квитанції-приймання" в API генерації в простому режимі.

Для довідки: python requests використовує timeout=300, urllib — urlopen(..., timeout=300), Node — req.setTimeout(300000), curl — --max-time 300.

Рекомендований перелік кінцевих точок

Шляхи /api/voice/clone/* і /api/music/generate-with-voice — це ланцюг клонування голосу першого покоління, не рекомендований для нових інтеграцій; натомість використовуйте 【Рекомендовано】 API голосового профілю.

Розширені параметри: Max Mode і Variety

Кінцеві точки генерації підтримують ці два необов'язкові параметри (якщо їх не передати, поведінка й ціна залишаються попередніми):

Ці параметри підтримують: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Подвійна ціна на практиці: кінцева точка за 0,6 ¥ стає 1,2 ¥ з max_mode; генерація з вибраним голосом коштує 1,2 ¥ за виклик, а з Max Mode — 2,4 ¥; кавер власним голосом із 【Рекомендовано】 API голосового профілю теж 1,2 ¥ за виклик (2,4 ¥ з max_mode).
• variety застосовується лише до сімейства suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); надсилання його з будь-якою іншою моделлю повертає 400.
• Звукові ефекти, стеми, concat, WAV і дії редагування Studio (crop, видалення ділянки, fade, реверс, зміна швидкості тощо) не приймають цих параметрів — явне надсилання повертає 400, щоб жоден параметр не ігнорувався тихо.
• variety — це ціле число від 0 до 4; а style_weight і weirdness_constraint — десяткові від 0 до 1, тож шкали різні.

Типові поля відповіді про пісню

Кінцеві точки генерації, каверу, extend, розділення та запиту зазвичай повертають масив пісень із такими полями:

Чотири кроки інтеграції (мінімальний робочий приклад)

Виконайте ці чотири кроки — і перша пісня готова; повний перелік полів кожного кроку є на відповідній сторінці в рекомендованому переліку кінцевих точок.

# 1) Надішліть запит на генерацію: 0,6 ¥, повертає 2 пісні
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Опитуйте завдання, доки status не стане completed (інтервал 3-5 секунд цілком доречний)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id, отриманий на кроці 1"}'

# 3) Отримайте адресу медіа: усі кінцеві точки читання безкоштовні; доступні song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "той самий song_id", "kind": "song"}'

Коли щось пішло не так: 401 / 402 / 403 / 429 описано в довіднику помилок; тайм-аути й подвійні списання — у розділі "Час очікування та налаштування тайм-ауту" вище; подробиці кожної кінцевої точки — у рекомендованому переліку нижче.

Рекомендації

• Новим інтеграціям варто використовувати suno-v6 в усьому ланцюгу.
• Для кінцевих точок, що вказують типову ціну, фактично списана сума відповідає поточним налаштуванням цін у бек-офісі та запитаній моделі.
• Кінцеві точки генерації зазвичай спершу повертають завдання; фінальне аудіо читайте через /api/music/query.
• wait_completion=true блокує до завершення і підходить для тестів із малим обсягом; у продакшені краще опитування.
• Кінцеві точки генерації можуть відповідати дуже довго — встановіть тайм-аут клієнта 300 секунд або більше і пам'ятайте, що "немає відповіді" не те саме, що "нічого не згенеровано"; див. розділ "Час очікування та налаштування тайм-ауту" вище.
• Можливості завантаження, каверу, replace і WAV залежать від акаунтів платформи та прав на вихідний кліп; у разі невдачі спершу прочитайте повернуті message або error_message.

Про цю документацію

Цю сторінку переструктурували відповідно до можливостей, які Create UI справді показує, і новим інтеграціям варто читати її першою. Старіша документація API й досі доступна в розділі "Стара документація API (сумісна)" для тих, хто хоче нею користуватися далі.