# Музыка

`POST /v1/audio/generations` — трек по описанию: `200` с результатом, не успел за 9 минут —
`202`. В SDK OpenAI метода нет — обычный `POST` с JSON. Поля — схема `MusicGenerationRequest` и `input_schema` модели.

```bash
curl https://api.souz.ai/v1/audio/generations \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: jingle-42" \
  -d '{"model": "suno-v6", "prompt": "бодрый инди-поп, женский вокал", "lyrics": "[Verse]\nУтро светит в окно\n[Chorus]\nСолнце, мы снова живём", "title": "Утро"}'
```

## Описание, текст и инструментал

- `prompt` — описание трека: жанр, настроение, инструменты, темп, голос; текст песни модель
  напишет на языке описания.
- `lyrics` — свой текст с разделами `[Verse]`, `[Chorus]`, `[Bridge]`: модель споёт его как
  написан. `title` — название трека вместе с `lyrics`, у моделей, чья карточка его
  объявляет; без него — первая строка текста.
- `instrumental: true` — трек без вокала, вместе с `lyrics` не присылается.

Звук — в `data[]` (`type: "audio"`, MP3). Модель, которая делает за запрос два варианта
трека, отдаёт оба (`data[0]` и `data[1]`, оба с `role: "result"`), и цена — за оба.

## Suno V6: версии и действия

`version` выбирает `v6`, `v6-mini` или `v6-wild` (без поля — `v6`). `action` выбирает
действие; без поля — `generate`. Точный набор включённых действий — в `input_schema`
модели.

| Действие | Исходное аудио | Основные поля |
|---|---|---|
| `generate` — музыка | нет | описание; `custom_mode: true` — свой стиль и текст |
| `sounds` — эффекты | нет | описание звука; `sound_loop`, `sound_tempo`, `sound_key`, `grab_lyrics` |
| `cover` — кавер | один файл | описание или свой стиль и текст |
| `extend` — продолжение | один файл | описание; `continue_at` — момент в секундах, включает свой стиль и текст |
| `add_vocals` — вокал | один файл | стиль, `lyrics`, `negative_tags` |
| `add_instrumental` — инструментал | один файл | стиль, `negative_tags` |
| `mashup` — смешивание | два файла | описание или свой стиль и текст |

Действия над готовым треком:

| Действие | Что передать | Результат |
|---|---|---|
| `replace_section` | трек; стиль в `prompt`, текст фрагмента в `lyrics`, `full_lyrics`, `start_seconds`, `end_seconds` | новые варианты трека |
| `separate_vocals` | трек | вокал и инструментал |
| `split_stems` | трек | все дорожки |
| `isolate_stem` | трек, `stem_name` из схемы | выбранный инструмент |
| `wav` | трек | WAV-файл |
| `midi` | `source_job` результата разделения; `source_file` дорожки — по желанию | партии и ноты в `result.midi` |
| `video` | трек; `author`, `domain_name` — по желанию | MP4-клип |
| `cover_image` | `source_job` созданной песни с текстом | изображения обложки |
| `lyrics` | тема в `prompt`, до 200 символов | варианты текста в `result.lyrics` |
| `boost_style` | описание стиля в `prompt` | улучшенный стиль в `result.result` |
| `timestamps` | трек | слова с таймкодами и волна |
| `persona` | трек, `name`, `description`; границы фрагмента и стиль — по желанию | `persona_id` для следующих запросов |

```json
{"model": "suno-v6", "action": "timestamps", "source_job": "job_…", "source_file": "file_…"}
```

## Исходный трек

- Свой готовый трек — `source_job` (ID задачи) и `source_file` (ID аудиофайла из её
  `data`): связь с исходной песней сохраняется. `source_job` и `reference_audio` вместе не
  передаются.
- Внешний звук — `reference_audio`: `file_…` из [`POST /v1/files`](https://souz.ai/docs/files.md) или
  HTTPS-ссылка. Для переработки нужен доступный файл длительностью до 8 минут.
- `extend` без `continue_at` продолжает исходные стиль и параметры; чтобы изменить их,
  задайте `continue_at` (меньше длительности трека), `version` — та же, что у исходного,
  или без поля.
- Персона — `persona_id` и `persona_model: style_persona` в `generate`, `cover`, `extend`;
  при создании и кавере включите `custom_mode`, при продлении задайте `continue_at`. Окно
  анализа персоны — 10–30 секунд (по умолчанию 0–30). Замена фрагмента — 10–60 секунд и не
  больше половины трека. Обложка создаётся один раз для исходной песни.

## Пределы полей

В режиме своего текста `prompt` — стиль (до 1000 символов), `lyrics` — слова (до 5000).
`duration_seconds` (10–360) — желаемая длительность для создания, кавера и смешивания.
`style_weight`, `weirdness` и `audio_weight` — от 0 до 1 с шагом 0.01 (последнее — только с
исходным аудио). `negative_tags` — что исключить, до 200 символов (кроме смешивания).
`vocal_gender` — пожелание `m` или `f`. Допустимые сочетания проверяются до постановки
задачи.

## Результат

Каждый аудиофайл может нести `title`, `duration_seconds`, `tags`, `lyrics`, `label`
(название дорожки), `cover_id` и `actions`. Обложки — отдельные файлы с `role: cover`.
Структурированные результаты — в `result` задачи и файлом с `type: json`. Все действия —
обычная задача: работают `Prefer: respond-async`, идемпотентность, события и вебхуки. Цена
зависит от действия и версии — строка `pricing.options` каталога.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.