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

---
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
```

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

`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](#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--по-умолчанию) с `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 | 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: "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` позже.