# Справочник по музыкальному API Minimax

## Авторизация

Все запросы требуют токен Bearer в заголовке Authorization.

```
Authorization: Bearer <MINIMAX_API_KEY>
Content-Type: application/json
```

**Базовый URL:** `https://api.minimax.io/v1/`

Получите ключ API на [platform.minimax.io](https://platform.minimax.io) в разделе Account Management > API Keys. Используйте ключ **Pay-as-you-go**: ключи Coding Plan не покрывают генерацию музыки.

---

## Конечная точка генерации музыки

```
POST https://api.minimax.io/v1/music_generation
```

### Тело запроса

```json
{
  "model": "music-2.5",
  "prompt": "Indie folk, melancholic, acoustic guitar, soft piano, female vocals",
  "lyrics": "[Verse]\nWalking through the autumn leaves\nNobody knows where I've been\n\n[Chorus]\nEvery road leads back to you",
  "audio_setting": {
    "sample_rate": 44100,
    "bitrate": 256000,
    "format": "mp3"
  },
  "output_format": "url",
  "stream": false
}
```

### Параметры

| Параметр | Тип | Обязателен | По умолчанию | Ограничения | Описание |
| --- | --- | --- | --- | --- | --- |
| `model` | string | Да | — | `"music-2.5"` | Идентификатор версии модели |
| `lyrics` | string | Да | — | 1–3500 символов | Текст песни с тегами структуры и переносами строк `\n` |
| `prompt` | string | Нет | `""` | 0–2000 символов | Описание стиля, настроения, жанра и инструментов |
| `audio_setting` | object | Нет | см. ниже | — | Параметры качества звука |
| `output_format` | string | Нет | `"hex"` | `"hex"` или `"url"` | Формат аудиоданных в ответе |
| `stream` | boolean | Нет | `false` | — | Включение потоковой выдачи, только для hex |

### Объект audio_setting

| Поле | Тип | Допустимые значения | По умолчанию | Описание |
| --- | --- | --- | --- | --- |
| `sample_rate` | integer | `16000`, `24000`, `32000`, `44100` | `44100` | Частота дискретизации в Гц |
| `bitrate` | integer | `32000`, `64000`, `128000`, `256000` | `256000` | Битрейт в бит/с |
| `format` | string | `"mp3"`, `"wav"`, `"pcm"` | `"mp3"` | Аудиоформат результата |

### Структурные теги (поддерживается 14)

Теги управляют построением песни. Ставьте каждый на отдельной строке перед текстом соответствующего раздела:

| Тег | Назначение |
| --- | --- |
| `[Intro]` | Инструментальное или вокальное вступление |
| `[Verse]` | Основной куплет |
| `[Pre Chorus]` | Нарастание перед припевом |
| `[Chorus]` | Основной припев или хук |
| `[Post Chorus]` | Раздел сразу после припева |
| `[Bridge]` | Контрастный раздел, обычно перед последним припевом |
| `[Interlude]` | Инструментальный проигрыш между разделами |
| `[Outro]` | Завершение песни |
| `[Transition]` | Короткий музыкальный переход |
| `[Break]` | Ритмический разрыв или пауза |
| `[Hook]` | Запоминающийся мелодический хук |
| `[Build Up]` | Нарастание интенсивности перед дропом или припевом |
| `[Inst]` | Чисто инструментальный раздел, без вокала |
| `[Solo]` | Инструментальное соло, например гитарное |

Теги входят в ограничение в 3500 символов.

### Успешный ответ (output_format: "url")

```json
{
  "trace_id": "0af12abc3def4567890abcdef1234567",
  "data": {
    "status": 2,
    "audio": "https://cdn.minimax.io/music/output_abc123.mp3"
  },
  "extra_info": {
    "music_duration": 187.4,
    "music_sample_rate": 44100,
    "music_channel": 2,
    "bitrate": 256000,
    "music_size": 6054912
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

### Успешный ответ (output_format: "hex")

```json
{
  "trace_id": "0af12abc3def4567890abcdef1234567",
  "data": {
    "status": 2,
    "audio": "fffb9064000000..."
  },
  "extra_info": {
    "music_duration": 187.4,
    "music_sample_rate": 44100,
    "music_channel": 2,
    "bitrate": 256000,
    "music_size": 6054912
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

### Поля ответа

| Поле | Тип | Описание |
| --- | --- | --- |
| `trace_id` | string | Уникальный идентификатор запроса для отладки |
| `data.status` | integer | `1` = выполняется, `2` = завершено |
| `data.audio` | string | URL аудио (режим url) или байты в шестнадцатеричном виде (режим hex) |
| `extra_info.music_duration` | float | Длительность в секундах |
| `extra_info.music_sample_rate` | integer | Фактически использованная частота дискретизации |
| `extra_info.music_channel` | integer | Число каналов (`2` = стерео) |
| `extra_info.bitrate` | integer | Фактически использованный битрейт |
| `extra_info.music_size` | integer | Размер файла в байтах |
| `base_resp.status_code` | integer | `0` = успех; остальные значения см. в кодах ошибок |
| `base_resp.status_msg` | string | Сообщение о статусе для человека |

### Потоковая выдача

Если задано `stream: true`:
- Работает только с `output_format: "hex"`, несовместима с `"url"`.
- Ответ приходит в виде событий Server-Sent Events (SSE).
- Каждый фрагмент содержит часть hex-данных в `data.audio`.
- У фрагментов с аудио стоит `data.status: 1`.
- Завершающий фрагмент содержит `data.status: 2` и сводные данные.
- Соедините все hex-фрагменты и преобразуйте их, чтобы получить полное аудио.

---

## Конечная точка генерации текста песни

```
POST https://api.minimax.io/v1/lyrics_generation
```

### Тело запроса

```json
{
  "mode": "write_full_song",
  "prompt": "A soulful blues song about a rainy night and lost love"
}
```

### Параметры

| Параметр | Тип | Обязателен | По умолчанию | Ограничения | Описание |
| --- | --- | --- | --- | --- | --- |
| `mode` | string | Да | — | `"write_full_song"` или `"edit"` | Режим генерации |
| `prompt` | string | Нет | — | 0–2000 символов | Описание темы, идеи или стиля |
| `lyrics` | string | Нет | — | 0–3500 символов | Существующий текст песни, только для режима edit |
| `title` | string | Нет | — | — | Название песни; при передаче сохраняется |

### Тело ответа

```json
{
  "song_title": "Rainy Night Blues",
  "style_tags": "Soulful Blues, Rainy Night, Melancholy, Male Vocals, Slow Tempo",
  "lyrics": "[Verse]\nThe streetlights blur through window pane\nAnother night of autumn rain\n\n[Chorus]\nYou left me standing in the storm\nNow all I have is memories warm",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}
```

### Поля ответа

| Поле | Тип | Описание |
| --- | --- | --- |
| `song_title` | string | Созданное или сохранённое название песни |
| `style_tags` | string | Описания стиля через запятую; используйте как музыкальный промпт |
| `lyrics` | string | Текст песни с тегами структуры, готовый для music_generation |
| `base_resp.status_code` | integer | `0` = успех |
| `base_resp.status_msg` | string | Сообщение о статусе |

### Два этапа работы

```
Step 1: POST /v1/lyrics_generation
        Input:  { mode: "write_full_song", prompt: "theme description" }
        Output: { song_title, style_tags, lyrics }

Step 2: POST /v1/music_generation
        Input:  { model: "music-2.5", prompt: style_tags, lyrics: lyrics }
        Output: { data.audio (url or hex) }
```

---

## Готовые настройки качества звука

### Узкий канал связи (самый маленький файл)
```json
{ "sample_rate": 16000, "bitrate": 64000, "format": "mp3" }
```

### Предпросмотр или черновик
```json
{ "sample_rate": 24000, "bitrate": 128000, "format": "mp3" }
```

### Обычное качество (рекомендуется по умолчанию)
```json
{ "sample_rate": 44100, "bitrate": 256000, "format": "mp3" }
```

### Профессиональная работа или импорт в DAW
```json
{ "sample_rate": 44100, "bitrate": 256000, "format": "wav" }
```

---

## Ограничения частоты и стоимость

| Тариф | Стоимость в месяц | Кредиты | RPM (запросов в минуту) |
| --- | --- | --- | --- |
| Starter | $5 | 100,000 | 10 |
| Standard | $30 | 300,000 | 50 |
| Pro | $99 | 1,100,000 | 200 |
| Scale | $249 | 3,300,000 | 500 |
| Business | $999 | 20,000,000 | 800 |

Расход кредитов за генерацию зависит от длительности аудио. Ссылки на аудио истекают через 24 часа.