# Музыка · Music API — neuraldeep.ru API

> Раздел машиночитаемой справки. Все разделы: https://neuraldeep.ru/llms.txt · всё одним файлом: https://neuraldeep.ru/llms-full.txt

Base URL: `https://api.neuraldeep.ru/v1`
Auth: `Authorization: Bearer $YOUR_KEY`

Генерация музыки тем же ключом, ручки под `/v1/music/*`. Модель Google Lyria 3 Pro: песня с вокалом по описанию стиля и тексту или инструментал, 48 кГц, mp3. Трек обычно готов секунд за 20–30.

Единица счёта — трек. Остаток видно в `GET /v1/music/quota`. На кошельке трек стоит 10 ₽. Списываются только готовые треки: упавшая задача квоту и деньги возвращает.

**Как устроено.** Всё асинхронно, формат свой, не OpenAI. `POST /v1/music/generate` создаёт задачу и сразу отвечает `{"task_id": "...", "status": "queued", "poll": "/v1/music/tasks/..."}`. Дальше опрашиваете `GET /v1/music/tasks/{id}`, пока `status` не станет `succeeded` или `failed` (по дороге `queued` и `running`). У готовой задачи есть `tracks[]` со ссылкой `url`. Файл забираете через `GET /v1/music/tasks/{id}/result?index=0`, пока трек не готов, эта ручка отвечает `409`.

| ручка | что |
|---|---|
| `POST /v1/music/generate` | генерация, JSON |
| `GET /v1/music/tasks/{id}` | статус и трек |
| `GET /v1/music/tasks/{id}/result?index=0` | трек файлом, по умолчанию mp3, другой формат задаёт `audio_format`: `wav`, `wav32`, `flac`, `opus`, `aac` |
| `GET /v1/music/quota` | остаток треков |
| `GET /v1/music/models` | доступные модели |

**Что писать в запрос.**

- `prompt`: стиль словами — жанр, инструменты, настроение, тип вокала. Например «мрачный синтвейв, аналоговые синты, женский вокал».
- `lyrics`: текст песни, можно с разметкой `[verse]`, `[chorus]`, `[bridge]`. Для трека без голоса напишите `[instrumental]`.
- `vocal_language`: язык вокала, например `ru` или `en`.
- `audio_duration`: желаемая длина в секундах, от 10 до 300. Это подсказка модели, точную длину она не гарантирует.
- `bpm`, `key_scale`, `time_signature`: темп, тональность, размер. Тоже подсказки.
- `seed`: повторить результат.

Поля вне списка отбрасываются молча. За раз одна песня, `batch_size` больше 1 даёт `422`. Каверы, правка куска и отдельные дорожки сейчас недоступны.

```bash
id=$(curl -s https://api.neuraldeep.ru/v1/music/generate \
  -H "Authorization: Bearer $YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"инди-поп, акустическая гитара, тёплый женский вокал","lyrics":"[verse]\nПо лужам до утра\n[chorus]\nМы снова дома","vocal_language":"ru","audio_duration":90}' | jq -r .task_id)

curl https://api.neuraldeep.ru/v1/music/tasks/$id \
  -H "Authorization: Bearer $YOUR_KEY"

curl "https://api.neuraldeep.ru/v1/music/tasks/$id/result?index=0" \
  -H "Authorization: Bearer $YOUR_KEY" -o track.mp3
```

```python
import time, httpx

H = {"Authorization": "Bearer $YOUR_KEY"}
job = httpx.post(
    "https://api.neuraldeep.ru/v1/music/generate", headers=H,
    json={"prompt": "весёлый поп-панк про кота, который ненавидит понедельники", "vocal_language": "ru"},
).json()
tid = job["task_id"]

for _ in range(120):
    st = httpx.get(f"https://api.neuraldeep.ru/v1/music/tasks/{tid}", headers=H).json()
    if st["status"] in ("succeeded", "failed"):
        break
    time.sleep(3)

audio = httpx.get(f"https://api.neuraldeep.ru/v1/music/tasks/{tid}/result?index=0", headers=H).content
open("track.mp3", "wb").write(audio)
```

**Ошибки.**

- `400`: пустой запрос: нет ни описания, ни текста.
- `402`: на кошельке не хватает денег на трек.
- `404`: задачи с таким номером нет у вашего ключа или генерация не удалась.
- `409`: трек ещё не готов.
- `422`: недоступный `task_type`, `batch_size` больше 1, файлы в запросе, параметр не того типа.
- `429`: кончилась квота (тело `quota_exceeded`, см. [начало](https://neuraldeep.ru/docs/start.md)).
- `503`: генерация временно недоступна, повторите позже.