API генерації в розширеному режимі

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

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

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

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

Оплата: платно, наразі типово 0,6 ¥ за виклик. За виклик зазвичай повертаються 2 пісні; фактично списана сума відповідає поточній конфігурації цін у бек-офісі.

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.

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

Headers

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

Примітки до розширених параметрів

Стать голосу vocal_gender

• Надсилайте m або male для чоловічого голосу, f або female для жіночого.
• Сервіс нормалізує male і female до m та f відповідно.
• За instrumental=true параметр статі голосу не надсилається в сервіс генерації.

Вплив стилю style_weight

Керує тим, наскільки сильно результат дотримується style_tags. Чим вище значення, тим більше результат тяжіє до вказаних тегів стилю.

Випадковість weirdness_constraint

Керує тим, наскільки результат варіюється й експериментує. Вищі значення зазвичай дають більше варіацій; нижчі — безпечніший результат.

Обидва числові параметри в межах від 0.0 до 1.0, і 0 є припустимим явним значенням. Лише повне пропускання поля означає «не вказано».

Заповнюючи їх, врахуйте, що це десяткові дроби, а не відсоткові цілі числа. Орієнтир: 0.0–0.3 консервативно, 0.4–0.6 збалансовано, 0.7–1.0 експериментальніше; без чітких уподобань використовуйте 0.5 або просто пропустіть. Приклад: weirdness_constraint: 0.5, ніколи 50 чи 50%.

За instrumental=true результат інструментальний, тож текст і стать голосу не діють так, як у співаній пісні; якщо потрібен вокал, надішліть false або пропустіть поле. Логічні поля мають використовувати true/false у JSON, а не рядки.

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

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nНіч опускається на море\nвечірній вітер проходить повз вікно',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Вечірній вітер біля моря',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Режим квитанції-приймання (необов'язково)

Ця кінцева точка також підтримує режим квитанції-приймання з API генерації в простому режимі: з "accept_mode": "async" у тілі (або заголовком X-Accept-Mode: async) кінцева точка одразу повертає 202 і номер квитанції, генерація триває у фоні, а поступ відстежується через GET /api/music/requests/{request_id}.

Підходить клієнтам, які не мають тримати довгі з'єднання або не хочуть, щоб тайм-аут було прочитано як «нічого не згенеровано». Без цього параметра поведінка точно як раніше.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Вечірній вітер біля моря",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

Форма відповіді та спосіб опитування описані в розділі «Режим квитанції-приймання» API генерації в простому режимі.

Перевірка параметрів

Ці випадки повертають HTTP 400, і message помилки називає недопустиме поле:

• style_weight або weirdness_constraint не є числом.
• Числове значення менше 0.0 або більше 1.0.
• vocal_gender не один з m, f, male, female.

Ліміти текстових полів

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

Повідомлення про помилку має вигляд style_tags must not exceed 1000 characters; received 2772: перше слово — назва поля, що перевищило ліміт, а в кінці — виміряна кількість, тож отримавши 400, скорочуйте за цими двома числами, а не пробуйте поле за полем. Загальні правила — в «Обмеження текстових полів» Огляду нового API.

Відповідь

Кінцева точка зазвичай повертає масив із 2 піснями. Асинхронний запит зазвичай починається зі стану pending; збережіть song_id і отримайте фінальний стан та адресу аудіо через API запиту пісень. Поля пісні ті самі, що в API генерації в простому режимі.

Сумісні поля

Новим інтеграціям варто всюди використовувати snake_case. Якщо один запит містить і snake_case, і camelCase, переважає значення в snake_case.