API/Справочник

Novasound API

Генерируйте музыку программно: один вызов создаёт задачу и тратит 1 кредит, возвращая ~4 клипа. Авторизация — по персональному ключу из раздела «Ключи API».

Введение

Базовый адрес API — /api/v1 на вашем домене Novasound. Все ответы — в формате application/json. Тела запросов (для POST) передавайте как JSON с заголовком Content-Type: application/json.

Аутентификация

Каждый запрос авторизуется секретным ключом в заголовке Authorization: Bearer <ключ>. Получить и перевыпустить ключ можно в разделе «Ключи API» личного кабинета.

⚠

Никогда не используйте секретный ключ в клиентском коде. Ключ даёт полный доступ к вашему балансу — все вызовы делайте со своего сервера. При компрометации сразу перевыпустите ключ («Сгенерировать» в кабинете): старый перестанет работать мгновенно.

Лимиты и кредиты

Один вызов POST /api/v1/generate списывает 1 кредит и возвращает примерно 4 клипа (разные версии модели). Если генерация завершилась ошибкой или таймаутом, кредит возвращается автоматически. Действуют общие пер-IP ограничения частоты запросов — при 429 повторяйте с задержкой.

Создать генерацию

Создаёт задачу генерации и сразу возвращает её id. Готовый результат забирайте опросом GET /api/v1/generate/{id}.

POST /api/v1/generate

Body · application/json

description

stringусловно

Свободное описание трека — модель сама напишет текст и подберёт стиль. Нужно передать либо description, либо prompt.

prompt

stringусловно

Собственный текст песни, если хотите свои слова вместо авто-генерации. Обычно сочетается с tags.

Пример запроса

● запрос

200 OKapplication/json

ответ

Статус задачи

Возвращает статус задачи и массив клипов. Опрашивайте раз в несколько секунд, пока status не станет терминальным.

GET /api/v1/generate/{id}

Path

stringrequired

Идентификатор задачи, полученный из POST /api/v1/generate.

Пример запроса

● запрос

200 OKapplication/json

ответ

Поля ответа

string

Идентификатор задачи.

status

string

submitted → processing → complete либо error / timeout.

clips[]

array

Клипы генерации. У готовых появляется audio_url и image_url.

clips[].audio_url

string

Прямая ссылка на аудио. Заполняется при status = complete.

error

string|null

Текст ошибки, если задача завершилась с error.

Баланс

Текущее количество кредитов и email аккаунта, которому принадлежит ключ.

GET /api/v1/me

Пример запроса

● запрос

200 OKapplication/json

ответ

Коды ответов

200OKЗапрос успешен, объект возвращён в теле ответа.

400Bad RequestНе передан ни description, ни prompt.

401UnauthorizedОтсутствует или неверный ключ API.

402Payment RequiredКредиты закончились — пополните баланс в кабинете.

404Not FoundЗадача с указанным id не найдена (или принадлежит другому аккаунту).

429Too Many RequestsПревышен лимит частоты запросов. Повторите с задержкой.