# Music · Music API — neuraldeep.tech API

> One section of the machine-readable reference. All sections: https://neuraldeep.tech/llms.txt · everything in one file: https://neuraldeep.tech/llms-full.txt

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

Music generation with the same key, endpoints under `/v1/music/*`. The model is Google Lyria 3 Pro: a song with vocals from a style description and lyrics, or an instrumental, 48 kHz, mp3. A track is usually ready in 20–30 seconds.

The unit is a track. The remainder is in `GET /v1/music/quota`. On the wallet a track costs 10 ₽. Only finished tracks are charged: a failed task returns the quota and the money.

**How it works.** Everything is asynchronous, with our own format, not OpenAI's. `POST /v1/music/generate` creates a task and answers right away with `{"task_id": "...", "status": "queued", "poll": "/v1/music/tasks/..."}`. Then poll `GET /v1/music/tasks/{id}` until `status` becomes `succeeded` or `failed` (`queued` and `running` on the way). A finished task has `tracks[]` with a `url`. Download the file via `GET /v1/music/tasks/{id}/result?index=0`; until the track is ready this endpoint answers `409`.

| endpoint | what |
|---|---|
| `POST /v1/music/generate` | generation, JSON |
| `GET /v1/music/tasks/{id}` | status and track |
| `GET /v1/music/tasks/{id}/result?index=0` | the track as a file, mp3 by default, `audio_format` picks another: `wav`, `wav32`, `flac`, `opus`, `aac` |
| `GET /v1/music/quota` | tracks remaining |
| `GET /v1/music/models` | available models |

**What to put in the request.**

- `prompt`: the style in words — genre, instruments, mood, vocal type. For example "dark synthwave, analog synths, female vocals".
- `lyrics`: the song text, `[verse]`, `[chorus]`, `[bridge]` markers are fine. For a track without a voice, write `[instrumental]`.
- `vocal_language`: the vocal language, for example `ru` or `en`.
- `audio_duration`: the desired length in seconds, 10 to 300. It is a hint to the model, the exact length is not guaranteed.
- `bpm`, `key_scale`, `time_signature`: tempo, key, time signature. Also hints.
- `seed`: reproduce a result.

Fields outside the list are silently dropped. One song per request, `batch_size` above 1 gives `422`. Covers, section edits and separate stems are not available now.

```bash
id=$(curl -s https://api.neuraldeep.tech/v1/music/generate \
  -H "Authorization: Bearer $YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"indie pop, acoustic guitar, warm female vocals","lyrics":"[verse]\nWalking home at dawn\n[chorus]\nWe are home again","vocal_language":"en","audio_duration":90}' | jq -r .task_id)

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

curl "https://api.neuraldeep.tech/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.tech/v1/music/generate", headers=H,
    json={"prompt": "upbeat pop punk about a cat who hates Mondays", "vocal_language": "en"},
).json()
tid = job["task_id"]

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

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

**Errors.**

- `400`: an empty request: no description, no lyrics.
- `402`: the wallet does not have enough money for the track.
- `404`: your key has no task with that id, or generation failed.
- `409`: the track is not ready yet.
- `422`: an unavailable `task_type`, `batch_size` above 1, files in the request, or a parameter of the wrong type.
- `429`: the quota is used up (`quota_exceeded` body, see [getting started](https://neuraldeep.tech/docs/start.md)).
- `503`: generation is temporarily unavailable, retry later.