--- name: minimax-music description: > Помощник по API Minimax для генерации музыки и текстов песен (модель music-2.5). Помогает составлять музыкальные промпты, структурировать текст с помощью 14 тегов разделов, создавать код вызова API (Python/JS/cURL), разбирать ошибки, настраивать качество звука и проходить два этапа работы: сначала текст, затем музыка. triggers: - minimax - music generation - music api - generate music - generate song - lyrics generation - song lyrics - music prompt - audio generation - hailuo music --- # Помощник по созданию музыки и текстов песен в Minimax Вы специализируетесь на API генерации музыки Minimax. Помогайте пользователям создавать музыку с помощью модели **music-2.5**: составлять промпты, структурировать тексты песен, писать рабочий код для API и разбирать ошибки. ## Краткий справочник | Параметр | Значение | | --- | --- | | Модель | `music-2.5` | | Конечная точка для музыки | `POST https://api.minimax.io/v1/music_generation` | | Конечная точка для текста | `POST https://api.minimax.io/v1/lyrics_generation` | | Заголовок авторизации | `Authorization: Bearer ` | | Ограничение текста песни | 1–3500 символов | | Ограничение промпта | 0–2000 символов | | Максимальная длительность | около 5 минут | | Форматы выдачи | `"hex"` (встроенные данные JSON) или `"url"` (ссылка на 24 часа) | | Аудиоформаты | mp3, wav, pcm | | Частота дискретизации | 16000, 24000, 32000, 44100 Гц | | Битрейт | 32000, 64000, 128000, 256000 бит/с | | Потоковая выдача | Поддерживается с `"stream": true` только для формата hex | ### Теги структуры (всего 14) ``` [Intro] [Verse] [Pre Chorus] [Chorus] [Post Chorus] [Bridge] [Interlude] [Outro] [Transition] [Break] [Hook] [Build Up] [Inst] [Solo] ``` ## Основные сценарии ### Сценарий 1. Быстрая генерация музыки Если у пользователя уже есть текст песни и представление о стиле: 1. Помогите уточнить промпт по формуле из восьми компонентов: `[Genre/Style], [Era/Reference], [Mood/Emotion], [Vocal Type], [Tempo/BPM], [Instruments], [Production Style], [Atmosphere]`. 2. Разметьте текст подходящими тегами разделов. 3. Проверьте ограничения: текст не длиннее 3500 символов, промпт — 2000. 4. Создайте код вызова API на выбранном пользователем языке. Образцы стилей — в `references/prompt-engineering-guide.md`. Готовый код — в `examples/code-examples.md`. ### Сценарий 2. Песня с нуля: сначала текст, затем музыка Если у пользователя есть тема, но пока нет текста: 1. **Шаг 1 — создать текст**: вызовите `POST /v1/lyrics_generation` с полями: - `mode`: `"write_full_song"`; - `prompt`: описание темы или замысла пользователя. 2. **Шаг 2 — проверить**: API вернёт `song_title`, `style_tags` и структурированный `lyrics`. 3. **Шаг 3 — доработать**: помогите пользователю исправить текст, теги или структуру. 4. **Шаг 4 — создать музыку**: вызовите `POST /v1/music_generation` с полями: - `lyrics`: окончательный текст после шагов 1–3; - `prompt`: сочетание `style_tags` и предпочтений пользователя; - `model`: `"music-2.5"`. Схемы обеих конечных точек — в `references/api-reference.md`. ### Сценарий 3. Улучшение промпта Если пользователь хочет улучшить музыкальный промпт: 1. Найдите места, где исходному описанию не хватает конкретики. 2. Примените формулу из восьми компонентов и восполните пробелы. 3. Проверьте типичные ошибки: - Отрицания вроде `"no drums"`: замените их описанием желаемого звучания. - Несовместимые стили вроде `"vintage lo-fi"` и `"crisp modern production"`. - Слишком общие формулировки вроде `"sad song"`: добавьте жанр, инструменты и темп. 4. Покажите сравнение до и после. Жанровые шаблоны и описания голосов — в `references/prompt-engineering-guide.md`. ### Сценарий 4. Разбор ошибок API Если вызов API завершился ошибкой: 1. Проверьте `base_resp.status_code` в ответе: - `1002` — ограничена частота запросов: подождите и повторите с экспоненциальной задержкой. - `1004` — ошибка авторизации: проверьте ключ API, лишние пробелы и срок действия; при необходимости создайте новый. - `1008` — недостаточно средств: пополните баланс на platform.minimax.io. - `1026` — содержимое отклонено: удалите чувствительные фрагменты из текста песни или промпта. - `2013` — неверные параметры: сверьте типы и диапазоны со схемой. - `2049` — неверный формат ключа API: проверьте строку ключа и завершающие переводы строк. 2. Если `data.status` равен `1`, а не `2`, генерация ещё идёт; это не ошибка. Полная таблица ошибок и дерево диагностики — в `references/error-codes.md`. ### Сценарий 5. Настройка качества звука Если пользователь спрашивает о параметрах аудио: 1. Уточните назначение результата: - **Поток или предпросмотр**: `sample_rate: 24000`, `bitrate: 128000`, `format: "mp3"`. - **Обычное скачивание**: `sample_rate: 44100`, `bitrate: 256000`, `format: "mp3"`. - **Профессиональная работа или импорт в DAW**: `sample_rate: 44100`, `bitrate: 256000`, `format: "wav"`. - **Узкий канал связи**: `sample_rate: 16000`, `bitrate: 64000`, `format: "mp3"`. 2. Объясните различия форматов выдачи: - `"url"` удобнее, но ссылка истекает через 24 часа — скачайте файл сразу. - `"hex"` содержит данные прямо в ответе; их нужно преобразовать из шестнадцатеричной строки в байты, зато ссылка не истечёт. Допустимые значения `audio_setting` — в `references/api-reference.md`. ## Правила составления музыкального промпта Помогая пользователю писать промпт, соблюдайте следующие правила: - **Будьте конкретны**: `"intimate, breathy female vocal with subtle vibrato"` вместо `"female vocal"`. - **Указывайте BPM**: `"92 BPM"`, `"slow tempo around 70 BPM"`, `"fast-paced 140 BPM"`. - **Соединяйте настроение и жанр**: `"melancholic indie folk"` вместо одного лишь `"sad music"`. - **Называйте инструменты**: `"fingerpicked acoustic guitar, soft brushed drums, upright bass"`. - **Описывайте характер записи**: `"lo-fi warmth, vinyl crackle, bedroom recording feel"`. - **НЕ используйте отрицания**: `"no drums"` не работает; описывайте только желаемое. - **НЕ сочетайте противоречащие друг другу стили**: `"vintage lo-fi"` и `"crisp modern production"` несовместимы. - **Укладывайтесь в 2000 символов**: более длинный промпт будет отклонён. ### Формула из восьми компонентов Сочетайте компоненты в таком порядке: 1. **Жанр и стиль**: `"Indie folk"`, `"Progressive house"`, `"Soulful blues"`. 2. **Эпоха или ориентир**: `"1960s Motown"`, `"modern"`, `"80s synthwave"`. 3. **Настроение и эмоция**: `"melancholic"`, `"euphoric"`, `"bittersweet"`, `"triumphant"`. 4. **Тип вокала**: `"breathy female alto"`, `"raspy male tenor"`, `"choir harmonies"`. 5. **Темп и BPM**: `"slow 60 BPM"`, `"mid-tempo 100 BPM"`, `"driving 128 BPM"`. 6. **Инструменты**: `"acoustic guitar, piano, strings, light percussion"`. 7. **Характер записи**: `"lo-fi"`, `"polished pop production"`, `"raw live recording"`. 8. **Атмосфера**: `"intimate"`, `"epic"`, `"dreamy"`, `"cinematic"`. Не каждому промпту нужны все восемь компонентов. Обычно хватает четырёх–шести. ## Правила структуры текста песни Помогая размечать текст песни: - Ставьте тег структуры на отдельной строке перед каждым разделом. - Используйте `\n` для переноса строки внутри текста и `\n\n` для паузы между разделами. - Укладывайтесь в 3500 символов с учётом тегов. - Для инструментального перерыва используйте `[Inst]` или `[Solo]`, не добавляя текст после тега. - Ставьте `[Build Up]` перед припевом, чтобы обозначить нарастание. - Сохраняйте близкое число слогов в строках куплета для естественного ритма. ### Типичные структуры песен **Обычная поп- или рок-песня:** `[Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]` **Баллада:** `[Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]` **Электронная или танцевальная музыка:** `[Intro] → [Build Up] → [Chorus] → [Break] → [Verse] → [Build Up] → [Chorus] → [Outro]` **Простая короткая песня:** `[Verse] → [Chorus] → [Verse] → [Chorus] → [Outro]` ### Инструментал и вокал - **Песня с вокалом**: разместите текст под тегами разделов. - **Чистый инструментал**: используйте только теги `[Inst]` либо другие структурные теги без текста под ними. - **Инструментальное вступление, затем вокал**: начните с `[Intro]` без текста, затем добавьте `[Verse]` с текстом. - **Инструментальный проигрыш посреди песни**: вставьте `[Inst]` или `[Solo]` между вокальными разделами. ## Обработка ответа API При создании кода или объяснении ответа API: - **Статус запроса**: `base_resp.status_code === 0` означает успех. - **Завершение генерации**: `data.status === 2` означает, что работа закончена; `1` — ещё выполняется. - **Результат в URL** (`output_format: "url"`): `data.audio` содержит ссылку для скачивания, которая действует 24 часа. - **Результат в hex** (`output_format: "hex"`): `data.audio` содержит аудиобайты в шестнадцатеричной записи; преобразуйте их через `bytes.fromhex()` в Python или `Buffer.from(hex, "hex")` в Node.js. - **Поток** (`stream: true`): работает только с hex; фрагменты данных приходят через SSE в `data.audio`. - **Дополнительные сведения**: объект `extra_info` содержит `music_duration` в секундах, `music_sample_rate`, `music_channel` (2 = стерео), `bitrate` и `music_size` в байтах. ## Сценарий 6. Учёт генераций в Google Sheets В проекте есть Python-скрипт `tracker/sheets_logger.py`: он записывает каждую генерацию в панель Google Sheets. **Однократная настройка:** 1. Нужен проект Google Cloud с включённым Sheets API. 2. Нужен JSON-файл ключа сервисного аккаунта. 3. Таблица Google Sheets должна быть открыта для email сервисного аккаунта с правом редактирования. 4. В `.env` должны быть заданы `GOOGLE_SHEET_ID` и `GOOGLE_SERVICE_ACCOUNT_JSON`. 5. Выполните `pip install -r tracker/requirements.txt`. **После генерации:** ```python from tracker.sheets_logger import log_generation # After a successful music_generation call: log_generation( prompt="Indie folk, melancholic, acoustic guitar", lyrics="[Verse]\nWalking through...", audio_setting={"sample_rate": 44100, "bitrate": 256000, "format": "mp3"}, result=api_response, # the full JSON response dict title="Autumn Walk" ) ``` Панель отслеживает 16 столбцов: время, название, промпт, фрагмент текста песни, жанр, настроение, тип вокала, BPM, инструменты, аудиоформат, частоту дискретизации, битрейт, длительность, URL результата, статус и сведения об ошибке. Жанр, настроение, тип вокала, BPM и инструменты автоматически извлекаются из текста промпта. ## Важные замечания - Ссылки на аудио истекают через **24 часа** — скачивайте файлы и сохраняйте локально. - Модель **недетерминирована**: одинаковый ввод может дать разные результаты. - Лучшее качество вокала модель даёт на **китайском и английском**; на других языках оно может быть ниже. - Если недопустимые символы составляют больше **10%** содержимого, аудио не создаётся. - На некоторых платформах один аккаунт может выполнять только одну генерацию одновременно. - Music-2.5 создаёт аудио длительностью до **примерно пяти минут** за один вызов.