Обзор документации Suno API

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

Для создания API-ключа достаточно зарегистрироваться по e-mail. Одна генерация стоит 0,6 юаня и возвращает 2 песни, включая скачивание в MP3/WAV, каверы, Extend, разделение на стемы и клонирование голоса. Базовый URL: https://www.suno-api.io.

На этой странице описаны доступные модели, все интерфейсы генерации и редактирования, биллинг и рекомендуемый порядок чтения. Если вы подключаетесь впервые, читайте сверху вниз; здесь же собраны точки входа для диагностики 401/403/429.

Быстрые ответы

Как получить API-ключ? Зарегистрируйтесь по e-mail, откройте консоль, перейдите в управление токенами и создайте токен. Ни номер телефона, ни карта не нужны.

Сколько стоит один вызов? Генерация стоит 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. Не передавайте true, false, 0 или 1 вместо них.
• Поля, помеченные как «нет», можно не передавать вовсе. Если назначение параметра неясно, лучше его опустить и позволить сервису применить поведение по умолчанию; не заменяйте «не передано» пустой строкой, null или 0, потому что 0 для части числовых полей — допустимое значение.
• Имена полей чувствительны к написанию. На странице каждого интерфейса указаны рекомендуемое поле и совместимые синонимы; передавайте их точно как в таблице. Там, где документация допускает и snake_case, и camelCase, не передавайте оба одновременно.
• Все поля длительности, оканчивающиеся на _s или Seconds, задаются в секундах и допускают дробные значения. Для меток времени Unix отдельно указано, в секундах они или в миллисекундах.
• Идентификатор, начинающийся с pending:, — это заполнитель платформы, а не реальный 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, 18–20 сентября 2026)

• Около 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 юаня за вызов и 2,4 юаня с Max Mode; кавер голосом из 【Рекомендуется】 API профиля голоса тоже стоит 1,2 юаня за вызов (2,4 с max_mode).
• variety действует только на семейство suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); при других моделях отправка возвращает 400.
• Звуковые эффекты, стемы, concat, WAV и действия редактирования Studio (обрезка, удаление участка, фейд, обратное воспроизведение, скорость и т. п.) этих параметров не знают: явная отправка возвращает 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 Russian 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 секунд и больше и помните, что «нет ответа» не равно «ничего не сгенерировано».
• Загрузка, кавер, замена и WAV зависят от аккаунтов платформы и прав на исходный клип; при ошибке сначала смотрите message или error_message.

О документации

Эта страница переработана под возможности, которые Create UI реально предоставляет; новым интеграциям стоит начинать с неё. Прежняя документация API осталась в разделе «Прежняя документация API (совместимость)» для тех, кто хочет сохранить старый способ работы.