Генерация музыки (Music API)

Music API превращает текст песни в готовый трек с вокалом. Работает по тому же ключу, что и модели: отдельной регистрации не нужно.

Endpoint и ключ

Base URL: https://console.zubriq.by/api/v1/music
Ключ — тот же sk-zq-… из кабинета, что и для API моделей. Заголовок: Authorization: Bearer sk-zq-…

Генерация асинхронная: запрос ставит задачу в очередь и сразу возвращает job_id, готовность проверяется опросом.

Шаг 1. Поставить задачу

POST /generate → 202

Поле	Тип	Описание
`lyrics`	строка, до 4000	Текст песни. Секции размечаются тегами `[verse]`, `[chorus]`, `[bridge]` — каждый на своей строке
`prompt`	строка, до 600	Необязательно: стиль, настроение, инструменты, тип вокала словами
`duration_sec`	число 10–300	Необязательно: верхняя граница длительности, по умолчанию 60

curl https://console.zubriq.by/api/v1/music/generate \
  -H "Authorization: Bearer sk-zq-..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "тёплая поп-баллада, мужской вокал, фортепиано",
    "lyrics": "[verse]\nГород засыпает к ночи\n[chorus]\nА мы поём",
    "duration_sec": 120
  }'

Ответ: {"job_id": "…", "status": "queued"}

Шаг 2. Дождаться трека

GET /jobs/{job_id} — статус проходит путь queued → running → completed либо error. Опрашивайте раз в 5–10 секунд; трёхминутный трек готовится несколько минут.

{
  "job_id": "...",
  "status": "completed",
  "url": "/api/v1/music/files/...",
  "duration_sec": 173.35,
  "price_byn": 1
}

Шаг 3. Скачать

GET /files/{job_id} отдаёт WAV (44.1 кГц, стерео) по тому же ключу. Файл хранится в нашем хранилище — ссылка ваша, чужие домены и их сроки жизни ни на что не влияют.

import requests, time

API = "https://console.zubriq.by/api/v1/music"
H = {"Authorization": "Bearer sk-zq-..."}

job = requests.post(f"{API}/generate", headers=H, json={
    "prompt": "тёплая поп-баллада, мужской вокал, фортепиано",
    "lyrics": "[verse]\nГород засыпает к ночи\n[chorus]\nА мы поём",
}).json()["job_id"]

while (st := requests.get(f"{API}/jobs/{job}", headers=H).json())["status"] in ("queued", "running"):
    time.sleep(5)

if st["status"] == "completed":
    audio = requests.get(f"{API}/files/{job}", headers=H).content
    open("song.wav", "wb").write(audio)

Оплата и лимиты

Списывается фиксированная сумма за успешный трек — она приходит в ответе поля price_byn. Неудачная генерация бесплатна: платить не за что. Расход виден в кабинете отдельной строкой.

Ограничения на организацию: две генерации одновременно и 20 треков в сутки. Нулевой баланс — ответ 402, пополнение в кабинете.

Ошибки

Код	Что значит
`401`	Ключ не передан, недействителен или отозван
`402`	Нулевой баланс кошелька организации
`422`	Не прошла валидация (нет `lyrics`, длина или `duration_sec` вне диапазона)
`429`	Превышен лимит: слишком часто, две активные задачи или суточная норма
`503`	Генерация музыки временно недоступна