398 lines
17 KiB
Markdown
398 lines
17 KiB
Markdown
---
|
||
name: suno
|
||
description: Используй когда пользователь просит создать музыку, текст песни, кавер, ремикс, мэшап, видео, или работать с Suno AI Music API. Покрывает генерацию музыки, тексты, разделение вокала/стемов, Persona, стили и конвертацию.
|
||
---
|
||
|
||
# Suno Music API Skill
|
||
|
||
Этот skill описывает MCP-сервер для работы с [Suno API](https://sunoapi.org) через 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
|
||
```
|
||
|
||
## Режимы генерации
|
||
|
||
Агент **сам определяет**, какой режим лучше подходит под запрос пользователя, и предлагает его. Пользователь может согласиться или попросить изменить режим.
|
||
|
||
Модель по умолчанию: **V5_5** (пользователь может выбрать другую).
|
||
|
||
| Режим | `customMode` | Когда предлагать |
|
||
|---|---|---|
|
||
| **Кастомный** *(основной)* | `true` | По умолчанию. Агент сам пишет текст, стиль, структуру |
|
||
| **Простой** | `false` | Если пользователь хочет быстро, без деталей, или говорит «просто сделай что-нибудь» |
|
||
|
||
*В простом режиме Suno сама генерирует всё по короткому описанию (до 500 симв.).*
|
||
|
||
### Кастомный режим (customMode: true) — основной
|
||
|
||
Агент пишет текст с мета-тегами `[Verse]`, `[Chorus]`, стиль и всю структуру. Используй [Prompt Engineering Guide](#prompt-engineering-guide) для составления промпта.
|
||
|
||
```
|
||
suno_generate_music
|
||
prompt: "///*****///\n\n[Intro]..."
|
||
customMode: true
|
||
instrumental: false
|
||
style: "genre: anthemic alternative rock..."
|
||
title: "Название трека"
|
||
negativeTags: "trap, electronic beats..."
|
||
model: "V5_5"
|
||
```
|
||
|
||
В `customMode: true` поля `style` и `title` обязательны. Если `instrumental: false` — ещё и `prompt` (он станет точным текстом).
|
||
|
||
### Простой режим (customMode: false) — альтернатива
|
||
|
||
Если пользователь не хочет деталей (или говорит «просто сделай трек»):
|
||
|
||
```
|
||
suno_generate_music
|
||
prompt: "Энергичный рок-трек о восхождении на гору, мужской вокал"
|
||
customMode: false
|
||
instrumental: false
|
||
model: "V5_5"
|
||
```
|
||
|
||
Suno сама напишет текст и аранжировку. До 500 символов в `prompt`.
|
||
|
||
## Основные сценарии
|
||
|
||
### 1. Сгенерировать песню (кастомный режим, основной)
|
||
|
||
Агент предлагает написать текст и стиль. Если пользователь согласен — использует Prompt Engineering Guide, формирует три блока (Lyrics, Style, Negative Prompt) и вызывает:
|
||
|
||
```
|
||
suno_generate_music
|
||
prompt: "///*****///\n\n[Verse]..."
|
||
customMode: true
|
||
instrumental: false
|
||
style: "genre: synthwave, 80s..."
|
||
title: "Название"
|
||
negativeTags: "trap, male vocals..."
|
||
model: "V5_5"
|
||
```
|
||
|
||
Вернёт `taskId`. Затем `suno_get_task_status` для результата: 2 трека с `audio_url`, `title`, `tags`, `duration`.
|
||
|
||
### 2. Сгенерировать песню (простой режим, если спешка)
|
||
|
||
```
|
||
suno_generate_music
|
||
prompt: "Мелодичный инди-фолк с акустической гитарой, мягким вокалом"
|
||
customMode: false
|
||
instrumental: false
|
||
model: "V5_5"
|
||
```
|
||
|
||
### 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
|
||
|
||
Когда пользователь просит создать песню, агент ведёт себя как **Suno AI Master Master Assistant**: профессионально, дружелюбно, на русском языке. Агент предлагает пользователю вариант (режим, модель V5_5, текст, стиль) — пользователь может согласиться, попросить правки или отказаться в пользу простого режима. Перед генерацией анализируй историю чата и учитывай ранее выбранные жанры и стили.
|
||
|
||
### Три обязательных блока промпта
|
||
|
||
Каждый промпт для `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 | SING ONE OCTAVE HIGHER]` |
|
||
| Без вокального интро | `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: "V5_5"
|
||
```
|
||
|
||
### Память и предпочтения
|
||
|
||
Если пользователь ранее запрашивал определённые жанры (например, «Philly Disco» или «Funk Carioca»), используй их автоматически в новых запросах, если это уместно.
|
||
|
||
### Проверка перед отправкой
|
||
|
||
**Кастомный режим (`customMode: true`, основной):**
|
||
- [ ] `customMode: true`, `instrumental`, `model: "V5_5"` (если пользователь не выбрал другую)
|
||
- [ ] `style` и `title` заполнены
|
||
- [ ] Для вокального трека (`instrumental: false`) заполнен `prompt` с текстом
|
||
- [ ] `style` не превышает лимит символов для выбранной модели
|
||
- [ ] `negativeTags` — список через запятые, без `no`
|
||
- [ ] Ударения **не** размечены заглавными буквами
|
||
|
||
**Простой режим (`customMode: false`, альтернативный):**
|
||
- [ ] `customMode: false`, `instrumental`, `model` указаны
|
||
- [ ] `prompt` — хорошее описание идеи (до 500 символов)
|
||
- [ ] `style` и `title` оставлены пустыми (не нужны)
|
||
|
||
## Обработка ошибок
|
||
|
||
| Код | Причина |
|
||
|---|---|
|
||
| 400 | Неверные параметры |
|
||
| 401 | Неверный API ключ |
|
||
| 429 | Недостаточно кредитов |
|
||
| 430 | Слишком частые запросы |
|
||
| 455 | Технические работы |
|
||
|
||
Если async-задача не завершилась за 15 минут, сервер вернёт таймаут — используй `suno_get_task_status` позже.
|