suno-mcp-server/.opencode/skills/suno/SKILL.md

name, description

name	description
suno	Используй когда пользователь просит создать музыку, текст песни, кавер, ремикс, мэшап, видео, или работать с Suno AI Music API. Покрывает генерацию музыки, тексты, разделение вокала/стемов, Persona, стили и конвертацию.

Suno Music API Skill

Этот skill описывает MCP-сервер для работы с Suno API через opencode.

Лимиты и цены

• Rate limit: 20 запросов на 10 секунд.
• Стоимость кредита: $0.005 USD.
• Кредиты не истекают.
• Сгенерированные файлы хранятся 15 дней.

Прокси

Если сервис недоступен из вашей сети, MCP сервер поддерживает прокси через переменные окружения (в порядке приоритета):

SUNO_HTTP_PROXY=http://user:pass@proxy:8080
HTTPS_PROXY=http://proxy:8080
HTTP_PROXY=http://proxy:8080

Режимы генерации

customMode определяет, КТО управляет созданием трека:

Режим	customMode	Кто делает музыку	prompt	style/title
Простой (по умолчанию)	false	Suno генерирует всё сама	Да (идея, до 500 симв.)	Не нужно
Кастомный	true	Агент пишет текст и стиль	Да (точный текст, до 3000/5000)	Обязательно

Простой режим (customMode: false) — по умолчанию

Агент по умолчанию всегда использует этот режим. Пользователь говорит идею — агент передаёт её в prompt, Suno сама пишет текст, аранжировку и всё остальное:

suno_generate_music
  prompt: "Энергичный рок-трек о восхождении на гору, мужской вокал"
  customMode: false
  instrumental: false
  model: "V4_5ALL"

Плюсы: быстро, дёшево, Suno отлично справляется сама. До 500 символов в prompt.

Кастомный режим (customMode: true) — когда нужен точный контроль

Агент сам пишет текст с мета-тегами [Verse], [Chorus] и описывает стиль. Используй ТОЛЬКО когда пользователь просит конкретный текст или определённые детали. Подробнее в Prompt Engineering Guide.

Основные сценарии

1. Сгенерировать песню (простой режим, по умолчанию)

suno_generate_music
  prompt: "Мелодичный инди-фолк с акустической гитарой, мягким вокалом, ностальгическое настроение"
  customMode: false
  instrumental: false
  model: "V4_5ALL"

Вернёт taskId. Затем suno_get_task_status для получения результата: 2 трека с audio_url, title, tags, duration.

3. Получить текст песни

suno_generate_lyrics
  prompt: "Песня о путешествии, вдохновляющая, indie pop"

Полученный текст можно передать в suno_generate_music(prompt=текст, customMode=true).

4. Разделить вокал и музыку

suno_separate_vocals
  taskId: "<taskId генерации>"
  audioId: "<id трека>"

Для продвинутого разделения по инструментам:

suno_separate_stems
  taskId: "<taskId>"
  audioId: "<id трека>"

5. Сделать кавер существующего аудио

suno_upload_and_cover
  uploadUrl: "https://example.com/my-song.mp3"
  customMode: true
  instrumental: false
  style: "Jazz"
  title: "Jazz Version"
  prompt: "[Verse] Smooth jazz arrangement..."
  model: "V4_5ALL"

6. Создать персону из трека

suno_generate_persona
  taskId: "<taskId>"
  audioId: "<id трека>"

Бесплатно. Возвращает personaId, который потом можно использовать в suno_generate_music (personaId + personaModel: style_persona) для единого стиля.

7. Узнать промпт по готовому треку

suno_get_task_status
  taskId: "<taskId генерации>"

В ответе будут поля prompt, title, tags для каждого трека.

Полный список инструментов

Инструмент	Назначение	Кредиты
suno_generate_music	Генерация музыки	12
suno_generate_lyrics	Генерация текста	0.4
suno_generate_sounds	Звуки/амбиенты/лупы	2.5
suno_extend_music	Продлить трек	12
suno_replace_section	Заменить фрагмент трека	5
suno_add_vocals	Добавить вокал на инструментал	12
suno_add_instrumental	Добавить инструментал к вокалу	12
suno_upload_and_cover	Загрузить аудио и сделать кавер	12
suno_upload_and_extend	Загрузить аудио и продлить	12
suno_generate_mashup	Мэшап из двух аудио	12
suno_separate_vocals	Вокал + минус	10
suno_separate_stems	Разделение по инструментам	20
suno_create_video	Видео из трека	2
suno_create_cover	Обложка трека	0
suno_convert_to_wav	Конвертация в WAV	0.4
suno_boost_style	Улучшить описание стиля	0.4
suno_generate_persona	Создать персону из трека	0
suno_get_task_status	Статус и метаданные трека	0
suno_get_timestamped_lyrics	Текст с таймкодами	0.5
suno_get_lyrics_details	Детали генерации текста	0
suno_get_wav_details	Детали конвертации WAV	0
suno_get_vocal_separation_details	Детали разделения	0
suno_get_video_details	Детали видео	0
suno_get_credits	Остаток кредитов	0

Выбор модели

Модель	Длина	Когда использовать
V4	до 4 мин	Лучшее качество звука
V4_5	до 8 мин	Умные промпты, быстрее
V4_5PLUS	до 8 мин	Более насыщенный звук
V4_5ALL	до 8 мин	Лучшая структура песни
V5	до 8 мин	Высокая музыкальность, скорость
V5_5	до 8 мин	Персонализированные голоса

Лимиты символов в customMode

Поле	V4	V4_5 / V4_5PLUS / V4_5ALL / V5 / V5_5
prompt	3000	5000
style	200	1000
title	80	100

В customMode: false только prompt, максимум 500 символов.

Prompt Engineering Guide

Этот раздел — только для customMode: true, когда пользователю нужен точный контроль над текстом и стилем трека. По умолчанию используй простой режим с customMode: false.

Когда пользователь просит создать песню, агент должен вести себя как Suno AI Master Assistant: профессионально, дружелюбно, на русском языке. Перед генерацией анализируй историю чата и учитывай ранее выбранные жанры и стили.

Три обязательных блока промпта

Каждый промпт для suno_generate_music (особенно в customMode: true) должен состоять из трёх блоков:

Блок А: Lyrics (текст с мета-тегами)

///*****///

[Verse]
Текст куплета
Четыре строки по 6–10 слогов

[Chorus | anthemic chorus | stacked harmonies]
Текст припева
Мощный, запоминающийся хук

[Bridge]
Текст бриджа
Контраст с основной частью

[break 0.5]

[Chorus]
Повтор припева
(RISE UP NOW!)

Правила:

• Разделитель ///*****/// в самом верху, чтобы промпт не «протекал» в вокал.
• Мета-теги: [Verse], [Chorus], [Bridge], [Pre-Chorus], [Intro], [Outro].
• Уточнение стиля секции через |: [Chorus | anthemic chorus | stacked harmonies].
• Паузы: [break 0.5] или [break 1.0 sek].
• Бэк-вокал в круглых скобках: (RISE UP NOW!).
• Строка: 6–10 слогов, секция: обычно 4 строки.
• Не размечай ударения заглавными буквами — Suno v5 и v5.5 самостоятельно хорошо ориентируются в ударениях.

Блок Б: Style (окно стиля)

Используй иерархическую структуру, разделённую точками:

genre: indie folk rock, 2020s bedroom pop.
vocal: [baritone male vocal], [raspy vocal tone], emotional delivery.
instrumentation: [nylon string guitar], [TR-808 kit], [warm analog synth pad].
recording & mastering: high quality studio recording, balanced EQ, crystal clear vocals, wide stereo image.

Важно: учитывай лимиты длины style:

Модель	Лимит style
V4	200 символов
V4_5 / V4_5PLUS / V4_5ALL / V5 / V5_5	1000 символов

Если стиль не влезает — сокращай менее важные части, сохраняя жанр и ключевые инструменты.

Блок В: Negative Prompt (исключения)

Передаётся в параметр negativeTags как список через запятые без слова no:

trap, male vocals, distortion, sawtooth synths, harsh highs, muddiness

Золотые правила по жанрам

Жанр	Что прописывать
Disco	[Arrangement: groove-based, repetitive, no development], four-on-the-floor kick, lush strings
Latin	Фокус на перкуссии: piano montuno, congas, bongos, clave. Меньше акцент на гармонии
Blues	12-bar form, shuffle feel, electric guitar, walking bass. Избегай поп-структур
Brazilian Funk	TR-808, tamborim syncopation, monophonic synth bass, Portuguese vocal samples
Electronic	Конкретные типы синтеза: FM synthesis bass, wavetable movement, granular pads. Избегай общих «saw synth»
Rock	live drum kit, electric guitars, bass guitar, analog saturation
Jazz	upright bass, brushed drums, piano trio, warm room reverb

Управление вокалом

Задача	Что писать в Style / Lyrics
Припев выше октавой	Style: chorus sung ONE OCTAVE HIGHER. Lyrics: `[Chorus
Без вокального интро	NO vocal intro, instrumental intro only, vocal starts with first verse
Сухой вокал	dry vocal recording, close-mic vocal, no reverb tails, minimal processing
Многослойный хор	stacked harmonies, doubled vocals, group choir backing
Шёпот	intimate whisper vocal, breathy tone, close microphone

Пример полного промпта

Пользователь: «Сделай энергичный рок-трек о восхождении на гору, мужской вокал».

Lyrics (передаётся в prompt):

///*****///

[Intro]
[instrumental intro only, no vocal]

[Verse]
Тяжёлый шаг, камень за камнем
Ветер рвёт дыханье, но не сбить меня
Каждый метр — битва, каждый вздох — победа
Вершина ближе, сердце как маяк

[Pre-Chorus]
Тень долины позади
Там, где страх остался жить

[Chorus | anthemic chorus | stacked harmonies]
Я поднимаюсь выше!
К небу, к солнцу, к огню!
Я поднимаюсь выше!
(RISE UP NOW!)
Никто не остановит путь мой

[break 0.5]

[Verse]
Снег под ногами, холод в руках
Но внутри пылает жар, что не погасить

[Chorus | SING ONE OCTAVE HIGHER]
Я поднимаюсь выше!
К небу, к солнцу, к огню!
Я поднимаюсь выше!
(RISE UP NOW!)

Style (передаётся в style):

genre: anthemic alternative rock, 2010s stadium rock.
vocal: [powerful male vocal], [baritone lead], raspy emotional tone, shouted gang vocals.
instrumentation: [live drum kit], [crunch electric guitar], [driving bass guitar], [piano accents], [synth pad layers].
recording & mastering: high quality studio recording, punchy drums, wide stereo guitars, clear vocal, analog warmth.

Negative Prompt (передаётся в negativeTags):

trap, electronic beats, female vocals, jazz chords, muddiness, weak drums

Вызов генерации

suno_generate_music
  prompt: "///*****///\n\n[Intro]..."
  customMode: true
  instrumental: false
  style: "genre: anthemic alternative rock..."
  title: "Восхождение"
  negativeTags: "trap, electronic beats, female vocals, jazz chords, muddiness, weak drums"
  model: "V4_5ALL"

Память и предпочтения

Если пользователь ранее запрашивал определённые жанры (например, «Philly Disco» или «Funk Carioca»), используй их автоматически в новых запросах, если это уместно.

Проверка перед отправкой

Простой режим (customMode: false, по умолчанию):

• customMode: false, instrumental, model указаны
• prompt — хорошее описание идеи (до 500 символов)
• style и title оставлены пустыми (не нужны)

Кастомный режим (customMode: true, только по запросу):

• customMode: true, instrumental, model указаны
• style и title заполнены
• Для вокального трека (instrumental: false) заполнен prompt с текстом
• style не превышает лимит символов для выбранной модели
• negativeTags — список через запятые, без no
• Ударения не размечены заглавными буквами

Обработка ошибок

Код	Причина
400	Неверные параметры
401	Неверный API ключ
429	Недостаточно кредитов
430	Слишком частые запросы
455	Технические работы

Если async-задача не завершилась за 15 минут, сервер вернёт таймаут — используй suno_get_task_status позже.