← МоиПесни.РФ

API v1

API МоиПесни.РФ

Создавайте по два варианта трека асинхронно. После запуска заказа получите результат через polling или HTTPS callback.

Base URL: https://api.моипесни.рф Формат: JSON UTF-8 Авторизация: Bearer

Быстрый старт

Доступ к API предоставляется по запросу. Для подключения свяжитесь с нами через страницу «Контакты».

Откройте в кабинете раздел «API и интеграция» и создайте API-токен.

Передавайте токен в заголовке Authorization с типом Bearer. Не размещайте токен в открытом доступе.

Authorization: Bearer msp_live_...
Content-Type: application/json
Idempotency-Key: order-2026-07-21-001

Idempotency-Key необязателен, но рекомендуется: повтор того же запроса с тем же ключом вернёт созданный ранее заказ без второго списания.

POST/v1/music/generations

Создание музыки

Запрос сразу возвращает ID заказа, а генерация продолжается асинхронно. Стоимость списывается с баланса аккаунта один раз; при технической ошибке генерации она возвращается автоматически.

Свои слова и стиль

curl -X POST 'https://api.моипесни.рф/v1/music/generations' \
  -H 'Authorization: Bearer msp_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-order-001' \
  -d '{
    "customMode": true,
    "instrumental": false,
    "model": "pro-6",
    "title": "Летний свет",
    "style": "indie pop, warm vocal, acoustic guitar",
    "prompt": "[Verse]\nГород просыпается...",
    "negativeTags": "heavy metal, aggressive drums",
    "vocalGender": "f",
    "callBackUrl": "https://example.com/webhooks/moi-pesni"
  }'

Генерация по описанию

{
  "customMode": false,
  "instrumental": false,
  "prompt": "Светлая поп-песня о летнем путешествии"
}
ПолеТипОбязательностьОписание
customModebooleanНетПо умолчанию false: prompt описывает идею песни, а текст при необходимости создаётся автоматически. При true вы передаёте точный текст песни, стиль и название.
instrumentalbooleanНетПо умолчанию false. Значение true создаёт трек без вокала. В custom mode тогда достаточно передать style и title, без prompt.
modelstringНетВерсия модели определяет характер генерации. Если поле не передано, используется pro-6. Доступны pro-6, pro-6-wild и pro-6-mini; подробное сравнение приведено ниже.
promptstringУсловноПри customMode=false это идея песни до 500 символов: жанр, настроение, сюжет, инструменты, темп и тип вокала. При customMode=true это точный текст до 5000 символов, который будет использован как слова песни; можно применять разметку [Verse], [Chorus], [Bridge].
stylestringcustomMode=trueМузыкальное задание до 1000 символов. Через запятую укажите жанр и поджанр, настроение, темп, инструменты, тип вокала и характер продакшена. Например: indie pop, dreamy, 105 bpm, warm female vocal, acoustic guitar.
titlestringcustomMode=trueНазвание трека. До 80 символов.
negativeTagsstringНетСтили, инструменты и черты, которых желательно избежать. Перечисляйте через запятую: heavy metal, distorted guitar, aggressive drums. До 1000 символов; работает только в custom mode и является пожеланием, а не строгим фильтром.
vocalGenderstringНетПредпочтительный тип вокала: m/male или f/female. Используется только в custom mode. Это направление для модели, а не гарантия конкретного тембра.
callBackUrlHTTPS URLНетАдрес, на который после завершения или ошибки заказа придёт POST с результатом. Максимум 2048 символов; разрешён только HTTPS. Приватные сети, логин и пароль в URL, а также фрагменты заблокированы.
styleWeightnumberНетНасколько сильно результат должен следовать полю style. Диапазон от 0 до 1: меньше — больше свободы модели, больше — сильнее влияние заданного стиля.
weirdnessConstraintnumberНетСтепень творческого отклонения и необычности. Диапазон от 0 до 1: низкие значения дают более предсказуемый результат, высокие — более экспериментальный.
audioWeightnumberНетСила влияния исходного аудио, когда операция работает с загруженным треком. Диапазон от 0 до 1. Для обычной генерации по тексту без исходного аудио параметр обычно не нужен.

Как выбрать модель

Поле model необязательно. Если не передать его в запросе, API автоматически выберет pro-6. Указывайте model только если хотите осознанно выбрать другую версию. Модели по-разному интерпретируют стиль и текст, поэтому при переходе между версиями один и тот же запрос может дать заметно отличающийся результат.

МодельОсобенностиКогда выбирать
pro-6Основная модель семейства Pro, используется по умолчанию.Универсальный стартовый вариант для новых интеграций.
pro-6-wildМодель для более экспериментальных и творческих результатов.Поиск необычного звучания и новых музыкальных идей.
pro-6-miniОблегчённая модель семейства Pro.Первые варианты песни и проверка музыкального замысла.

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

Точная настройка результата

styleWeight, weirdnessConstraint и audioWeight принимают числа от 0.00 до 1.00. Значение округляется до двух знаков после запятой. Если поле не передано, используются внутренние настройки выбранной модели.

styleWeight

Увеличивайте, если жанр, инструменты и настроение из style важнее разнообразия. Уменьшайте, если хотите дать модели больше свободы. Слишком высокое значение может сократить вариативность двух результатов.

weirdnessConstraint

Увеличивайте для необычных гармоний, неожиданных переходов и экспериментального звучания. Уменьшайте для более привычной и предсказуемой композиции.

audioWeight

Определяет, насколько результат должен сохранять особенности исходного аудио. Имеет практический смысл для операций с загруженным треком; при генерации только из текста его можно не указывать.

Практический подход: сначала выполните запрос без коэффициентов. Если нужен более управляемый результат, меняйте по одному параметру за раз. Для первого эксперимента можно использовать 0.65, но это пример, а не гарантированное значение по умолчанию.

Заказ принят: HTTP 202 Accepted

После отправки POST /v1/music/generations API не ждёт окончания генерации. Для нового заказа он сразу возвращает HTTP-статус 202 Accepted: запрос принят и поставлен в обработку, но треки ещё не готовы. Сохраните data.id из ответа — по нему можно проверять состояние заказа через GET /v1/orders/{id}. Если указан callBackUrl, итоговый результат также придёт на этот адрес.

{
  "data": {
    "id": "019c...",
    "type": "music_generation",
    "status": "pending",
    "price": "25.00",
    "currency": "RUB",
    "result": null,
    "error": null,
    "callback": {"requested": true, "status": "pending", "attempts": 0}
  },
  "meta": {"idempotent_replay": false}
}

При повторе того же запроса с тем же Idempotency-Key новый заказ не создаётся: API возвращает существующий заказ с HTTP 200 OK и meta.idempotent_replay=true.

GET/v1/orders/{id}

Получение результата

Опрашивайте заказ не чаще одного раза в 3–5 секунд. Терминальные состояния — completed и failed.

{
  "data": {
    "id": "019c...",
    "status": "completed",
    "result": {
      "tracks": [
        {
          "id": "track-uuid",
          "title": "Летний свет",
          "audio_url": "https://.../track.mp3",
          "image_url": "https://.../cover.jpg",
          "video_url": null,
          "duration": 182.4
        }
      ]
    }
  }
}

Callback

Если передан callBackUrl, после завершения генерации на этот адрес будет отправлен POST-запрос с результатом в формате JSON.

{
  "code": 200,
  "msg": "success",
  "data": {
    "callbackType": "complete",
    "task_id": "019c...",
    "taskId": "019c...",
    "status": "SUCCESS",
    "data": [
      {
        "id": "track-uuid",
        "audio_url": "https://.../track.mp3",
        "image_url": "https://.../cover.jpg"
      }
    ]
  }
}

Отвечайте любым HTTP 2xx. При недоступности callback результат всё равно остаётся доступен через GET заказа.

Лимиты и ошибки

  • 120 запросов в минуту на API-токен.
  • До 5 новых заказов музыки в минуту на API-токен.
  • По умолчанию не более 10 одновременно активных заказов; администратор может изменить лимит.
  • При HTTP 429 используйте заголовок Retry-After.
  • При HTTP 402 пополните баланс; в details указаны доступная и требуемая суммы.
{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance.",
    "details": {"available": "10.00", "required": "25.00", "currency": "RUB"}
  }
}