Suno API

Suno API

Suno создаёт музыку: полноценные песни с вокалом и текстом, инструментальные треки, джинглы и звуковые атмосферы. Через API доступны два режима:

• create_track - создать трек. В простом варианте вы описываете идею одной фразой, и модель сама пишет текст и музыку. В продвинутом - передаёте свой текст песни, стиль, название и длительность.
• sounds - звуки и атмосферы: дождь, город, костёр, шум кафе и другие фоновые звуки, при желании зацикленные.

Каждый запуск создаёт асинхронную операцию и возвращает два варианта трека на один запрос. Остальные режимы формы сайта (продление, замена фрагмента, добавление вокала или инструментала, каверы, мэшапы и работа с загруженным аудио) через API недоступны.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Запрос создаёт операцию и сразу возвращает id и стартовый статус queued.
• Выполнение асинхронное: трек обычно готов через 1-3 минуты, звуки - быстрее.

Доступные сценарии:

1. Простой режим - customMode: "false", идея трека в prompt_simple.
2. Продвинутый режим - customMode: "true", свой текст в prompt_lyrics, стиль в style, название в title, длительность в duration.
3. Инструментал - instrumental: "true" в любом из двух режимов; в продвинутом текст песни тогда не нужен.
4. Звуки и атмосферы - suno_generation_type: "sounds" и описание в sounds_prompt.

Тело запроса

{
  "tool": "suno",
  "input": {
    "...": "..."
  }
}

• tool - slug нейросети, здесь всегда "suno".
• input - параметры конкретного запуска.
• Все поля передаются напрямую внутри input, без дополнительного вложенного объекта input.
• Значения полей-переключателей customMode и instrumental передаются строками "true" или "false".

Параметры

Общие

Параметр	Тип	Обязательный	Описание
suno_generation_type	enum	Нет	Режим: create_track (создать трек, по умолчанию) или sounds (звуки и атмосферы).

Создание трека (create_track)

Параметр	Тип	Обязательный	Описание
customMode	enum	Нет	"false" - простой режим (по умолчанию), "true" - продвинутый.
instrumental	enum	Нет	"false" - с вокалом (по умолчанию), "true" - инструментал без слов.
suno_model	enum	Нет	Модель: V6 (по умолчанию, лучшее качество), V6_MINI (быстрее и проще), V6_WILD (более смелые и экспериментальные аранжировки).
prompt_simple	string	Да, в простом режиме	Идея трека одной-двумя фразами, от 3 до 3000 символов: о чём песня, жанр, настроение, вокал, темп. Модель сама напишет текст.
prompt_lyrics	string	Да, в продвинутом режиме с вокалом	Текст песни, от 3 до 5000 символов. Размечайте структуру тегами в квадратных скобках: [Куплет], [Припев], [Бридж], [Intro], [Outro]. Для дуэта можно подписать части: [Куплет - мужской вокал].
style	string	Да, в продвинутом режиме	Стиль трека, от 2 до 1000 символов. Лучше всего работают короткие теги через запятую на английском: жанр, настроение, инструменты, вокал, темп. Например: acoustic wedding ballad, male and female duet, fingerpicked guitar, 72 BPM.
title	string	Да, в продвинутом режиме	Название трека, до 80 символов.
duration	number	Нет, только в продвинутом режиме	Длительность в секундах, от 10 до 360. По умолчанию 360. В простом режиме длительность выбирает модель.
use_advanced	boolean	Нет	Включает тонкие настройки styleWeight, weirdnessConstraint и audioWeight: без true они не отправляются модели. и учитываются, если заполнены, независимо от этого флага. Только в продвинутом режиме.

Звуки и атмосферы (sounds)

Параметр	Тип	Обязательный	Описание
sounds_prompt	string	Да	Описание звука или атмосферы, от 3 до 500 символов. Перечисляйте конкретные источники звука: «дождь по крыше, далёкий гром, дрова в печке».
sounds_model	enum	Нет	Модель: V6 (по умолчанию), V6_MINI, V6_WILD.
sounds_loop	boolean	Нет	true - сделать звук зацикленным, чтобы он бесшовно повторялся. По умолчанию false.
sounds_tempo	number	Нет	Темп в BPM, от 1 до 300. Имеет смысл для ритмичных звуков.
sounds_key	enum	Нет	Тональность: C, C#, D, D#, E, F, F#, G, G#, A, A#, B и минорные Cm, C#m, Dm, D#m, Em, Fm, F#m, Gm, G#m, Am, A#m, Bm. Если не нужна, не передавайте поле.
sounds_grab_lyrics	boolean	Нет	true - дополнительно получить текст, если в звуке есть речь или пение. По умолчанию false.

Примеры запросов

Сценарий 1. Простой режим: трек по идее

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "suno",
    "input": {
      "customMode": "false",
      "instrumental": "false",
      "suno_model": "V6",
      "prompt_simple": "Лиричная русская поп-баллада о возвращении домой поздней осенью. Женский вокал, фортепиано и струнные, медленный темп, запоминающийся припев"
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'suno',
    input: {
      customMode: 'false',
      instrumental: 'false',
      suno_model: 'V6',
      prompt_simple:
        'Лиричная русская поп-баллада о возвращении домой поздней осенью. Женский вокал, фортепиано и струнные, медленный темп, запоминающийся припев',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'suno',
        'input': {
            'customMode': 'false',
            'instrumental': 'false',
            'suno_model': 'V6',
            'prompt_simple': 'Лиричная русская поп-баллада о возвращении домой поздней осенью. Женский вокал, фортепиано и струнные, медленный темп, запоминающийся припев',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 2. Продвинутый режим: свой текст, стиль и название

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "suno",
    "input": {
      "customMode": "true",
      "instrumental": "false",
      "suno_model": "V6",
      "title": "С днём рождения, Маша!",
      "style": "cheerful kids pop, ukulele, hand claps, bright female vocal, 120 BPM",
      "duration": 60,
      "prompt_lyrics": "[Куплет]\nСегодня праздник у тебя, Маша,\nШары летят, и торт на столе\n\n[Припев]\nС днём рождения, Маша, с днём рождения!\nПусть сбываются мечты!"
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'suno',
    input: {
      customMode: 'true',
      instrumental: 'false',
      suno_model: 'V6',
      title: 'С днём рождения, Маша!',
      style:
        'cheerful kids pop, ukulele, hand claps, bright female vocal, 120 BPM',
      duration: 60,
      prompt_lyrics: [
        '[Куплет]',
        'Сегодня праздник у тебя, Маша,',
        'Шары летят, и торт на столе',
        '',
        '[Припев]',
        'С днём рождения, Маша, с днём рождения!',
        'Пусть сбываются мечты!',
      ].join('\n'),
    },
  }),
})

const data = await response.json()

Python

import requests

lyrics = """[Куплет]
Сегодня праздник у тебя, Маша,
Шары летят, и торт на столе

[Припев]
С днём рождения, Маша, с днём рождения!
Пусть сбываются мечты!"""

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'suno',
        'input': {
            'customMode': 'true',
            'instrumental': 'false',
            'suno_model': 'V6',
            'title': 'С днём рождения, Маша!',
            'style': 'cheerful kids pop, ukulele, hand claps, bright female vocal, 120 BPM',
            'duration': 60,
            'prompt_lyrics': lyrics,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 3. Инструментал с дополнительными параметрами

Текст песни не нужен. Чтобы веса styleWeight и weirdnessConstraint учитывались, передайте use_advanced: true.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "suno",
    "input": {
      "customMode": "true",
      "instrumental": "true",
      "suno_model": "V6",
      "title": "Ночной дрифт",
      "style": "phonk, cowbell melody, distorted 808 bass, dark, aggressive, 140 BPM",
      "duration": 45,
      "use_advanced": true,
      "negativeTags": "vocals, acoustic guitar",
      "styleWeight": 0.8,
      "weirdnessConstraint": 0.4
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'suno',
    input: {
      customMode: 'true',
      instrumental: 'true',
      suno_model: 'V6',
      title: 'Ночной дрифт',
      style:
        'phonk, cowbell melody, distorted 808 bass, dark, aggressive, 140 BPM',
      duration: 45,
      use_advanced: true,
      negativeTags: 'vocals, acoustic guitar',
      styleWeight: 0.8,
      weirdnessConstraint: 0.4,
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'suno',
        'input': {
            'customMode': 'true',
            'instrumental': 'true',
            'suno_model': 'V6',
            'title': 'Ночной дрифт',
            'style': 'phonk, cowbell melody, distorted 808 bass, dark, aggressive, 140 BPM',
            'duration': 45,
            'use_advanced': True,
            'negativeTags': 'vocals, acoustic guitar',
            'styleWeight': 0.8,
            'weirdnessConstraint': 0.4,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Сценарий 4. Звуки и атмосферы

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "suno",
    "input": {
      "suno_generation_type": "sounds",
      "sounds_model": "V6",
      "sounds_prompt": "Дождь стучит по крыше дачного домика, далёкий гром, в печке потрескивают дрова, тихий скрип старого кресла",
      "sounds_loop": true
    }
  }'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'suno',
    input: {
      suno_generation_type: 'sounds',
      sounds_model: 'V6',
      sounds_prompt:
        'Дождь стучит по крыше дачного домика, далёкий гром, в печке потрескивают дрова, тихий скрип старого кресла',
      sounds_loop: true,
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'suno',
        'input': {
            'suno_generation_type': 'sounds',
            'sounds_model': 'V6',
            'sounds_prompt': 'Дождь стучит по крыше дачного домика, далёкий гром, в печке потрескивают дрова, тихий скрип старого кресла',
            'sounds_loop': True,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "suno",
  "cost": 10,
  "balance_after": 495,
  "created_at": "2026-09-17T12:00:00Z"
}

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "suno",
  "cost": 10,
  "created_at": "2026-09-17T12:00:00Z",
  "completed_at": "2026-09-17T12:02:10Z",
  "result": {
    "type": "audio",
    "urls": [
      "https://storage.bratuha.ru/results/suno/track-1.mp3",
      "https://storage.bratuha.ru/results/suno/track-2.mp3"
    ],
    "files": [
      { "url": "https://storage.bratuha.ru/results/suno/track-1.mp3", "name": "track-1" },
      { "url": "https://storage.bratuha.ru/results/suno/track-2.mp3", "name": "track-2" }
    ]
  },
  "error_message": null
}

Ответ с ошибкой

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "suno",
  "cost": 10,
  "created_at": "2026-09-17T12:00:00Z",
  "completed_at": "2026-09-17T12:00:30Z",
  "result": null,
  "error_message": "Не удалось создать трек. Попробуйте изменить описание."
}

Проверка статуса

После создания операции сохраните id и проверяйте её статус запросом:

GET /api/v1/operations/{id}

cURL

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

JavaScript / TypeScript

const response = await fetch(
  'https://bratuha.ru/api/v1/operations/op_uuid-123',
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  }
)

const data = await response.json()

Пока трек создаётся, status будет queued или processing. Генерация песни занимает 1-3 минуты, поэтому опрашивайте статус раз в 10-15 секунд.

Формат результата

После успешного завершения result содержит аудио:

{
  "type": "audio",
  "urls": [
    "https://storage.bratuha.ru/results/suno/track-1.mp3",
    "https://storage.bratuha.ru/results/suno/track-2.mp3"
  ],
  "files": [
    { "url": "https://storage.bratuha.ru/results/suno/track-1.mp3", "name": "track-1" },
    { "url": "https://storage.bratuha.ru/results/suno/track-2.mp3", "name": "track-2" }
  ]
}

• type всегда равен "audio".
• urls - две ссылки на MP3: Suno на каждый запрос создаёт два варианта трека, выбирайте лучший.
• files дублирует те же ссылки с именами файлов.

Ценообразование

• Создание трека и звуков стоит 10 ₽ за запуск, независимо от режима, модели и длительности. За эти деньги приходят два варианта.
• Сумма списывается при создании операции и видна в поле cost ответа.
• Другие строки прайсинга (WAV, MP4, разделение вокала и стемов) относятся к действиям с готовым треком в форме сайта и через API недоступны.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую операцию и списывает деньги.
• Операция выполняется асинхронно: после queued проверяйте статус по id.
• Через API доступны только create_track и sounds. Значения extend, replace_section, add_vocals, add_instrumental, upload_cover, upload_extend и mashup вернут validation_error.
• В простом режиме передавайте prompt_simple, в продвинутом - prompt_lyrics, style и title. Если в продвинутом режиме включён instrumental: "true", текст песни не нужен.
• duration учитывается только в продвинутом режиме. В простом режиме модель сама выбирает длину, обычно 2-3,5 минуты.
• Suno хорошо поёт по-русски: текст в prompt_lyrics можно писать на русском, а стиль в style лучше задавать английскими тегами.
• Указывайте самое важное в начале style: жанр и настроение, затем вокал, инструменты и темп. 8-15 коротких тегов работают лучше длинных предложений.
• Для рекламных джинглов и коротких заставок ставьте duration 20-30 секунд и повторяйте название бренда в припеве.
• Для фоновых звуков включайте sounds_loop: true, чтобы файл можно было бесшовно зациклить в плеере.