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 или пропустите поле. Логические поля должны использовать JSON true/false, а не строки.

Пример запроса на 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.