Сгенерировать музыку

POSThttps://api.souz.ai/v1/audio/generations

Трек по описанию — с текстом песни, который напишет модель, со своим текстом (lyrics) или без вокала (instrumental). Ждёт результат и отвечает 200 с завершённой задачей: звук — в data[], у моделей, которые за один запрос дают два варианта трека, — оба, по порядку. Не успело за 9 минут или прислан Prefer: respond-async — 202 с задачей в работе.

Задача, провалившаяся во время ожидания, отвечает статусом по причине (400 invalid_input/content_policy/capability_mismatch, 502 generation_failed или unknown_error, 503 model_unavailable) и телом — объектом задачи с error.

Авторизация

BearerAuth

API-ключ из кабинета souz.ai — запускает модели. Ключ управления здесь не подходит: 403 forbidden с detail[].reason: requires_api_key.

Заголовки

Preferstring

RFC 7240. Понимаем respond-async — не ждать результат, сразу ответить 202 с задачей; остальные предпочтения игнорируются. Долгим моделям — вместе с Idempotency-Key и вебхуком (callback_url): ответ всегда 202, один путь кода.

Пример: "respond-async"

Idempotency-Keystring

Строка до 255 символов, уникальная для аккаунта. Повтор с тем же ключом и параметрами возвращает ту же задачу с текущим статусом без новой задачи и повторного списания, в том числе при одновременных запросах, даже если настройки аккаунта за это время изменились: сравниваются только поля запроса. Другие параметры — 409 idempotency_key_conflict; store и callback_url в сравнение не входят. У изображений, видео и музыки также не сравнивается response_format; у синтеза речи формат звука сравнивается. Ключ хранится вместе с задачей, сейчас без ограничения срока. Повтор задачи со статусом failed не запускает её заново: для новой попытки нужен новый ключ. Срок хранения файлов результата — retention.files_days из GET /v1/key; повтор его не продлевает. Поддерживается для генерации изображений, видео и музыки, транскрибации, синтеза речи и чата. У чата сравнивается тело запроса целиком; повтор дожидается идущего вызова и получает тот же ответ (и поток), что первый; ответ хранится сутки.

Максимальная длина: 255

Тело запроса обязательно

application/json

Схема MusicGenerationRequest

Других полей нет.

actionstring

Действие с музыкой или звуком; без поля — создание музыки.

Значения:

generate, sounds, cover, extend, add_vocals, add_instrumental, mashup, replace_section, separate_vocals, split_stems, isolate_stem, wav, midi, video, cover_image, lyrics, boost_style, timestamps, persona, voice_validate, voice_generate, voice_regenerate, voice_check

audio_weightnumber

Влияние аудиоэлементов; доступно и при создании в custom_mode.

Минимум: 0

Максимум: 1

authorstring

Автор.

callback_urlstring · uri

Куда прислать вебхук — https на публичный хост; без поля — адрес по умолчанию из настроек аккаунта.

continue_atnumber

С какой секунды продолжить исходный трек.

Минимум: 0.01

custom_modeboolean

Создание по своему стилю и тексту; для инструментала текст не нужен.

descriptionstring

Описание.

domain_namestring

Подпись сайта.

duration_secondsinteger

Желаемая длительность в режиме своего текста или стиля.

Минимум: 10

Максимум: 360

end_secondsnumber

Конец фрагмента.

full_lyricsstring

Полный текст после замены.

grab_lyricsboolean

Сохранить текст звука.

instrumentalboolean | null

Трек без вокала.

languagestring

Язык проверки голоса.

lyricsstring

Текст песни — модель споёт его как написан; разделы размечаются [Verse], [Chorus], [Bridge]. Без поля текст пишет модель. Вместе с instrumental не присылается.

max_price_multiplierMaxPriceMultiplier | null

modelstringобязательно

Пример: "suno-v6"

namestring

Имя.

negative_tagsstring

Какие стили и элементы исключить.

Максимальная длина: 200

persona_idstring

ID задачи Союза, создавшей персону или голос.

persona_modelstring

Тип сохранённой персоны.

Значения: style_persona, voice_persona

promptstring

Описание трека: жанр, настроение, инструменты, темп, голос. Язык текста песни, который напишет модель, — язык описания. В custom_mode и при lyrics это музыкальный стиль.

reference_audioarray[string]

Входные аудиофайлы — ссылки https или идентификаторы загруженных файлов.

Максимум элементов: 2

routingRouting

routing_optionsRoutingOptions | null

singer_skill_levelstring

Уровень вокала.

sound_keystring

Тональность звука из схемы параметров модели.

sound_loopboolean

Зацикленный звук.

sound_tempointeger

Темп звука в ударах в минуту.

Минимум: 1

Максимум: 300

source_filestring

ID аудиофайла из data исходной задачи.

source_jobstring

ID готовой задачи Союза, принадлежащей вашему аккаунту.

start_secondsnumber

Начало фрагмента.

stem_namestring

Дорожка или инструмент.

storeboolean | null

false — запрос без хранения: тексты запроса и ответа не сохраняются; файлы живут обычный срок. По умолчанию тексты хранятся; true не отменяет режим без хранения аккаунта.

style_weightnumber

Точность следования стилю.

Минимум: 0

Максимум: 1

titlestring

Название в режиме своего текста или стиля и при переработке аудио. Без него — первая строка текста песни или описания. В простом режиме название выбирает модель.

userstring

Поле OpenAI (id конечного пользователя); принимается, ни на что не влияет и не хранится.

versionstring

Версия модели из её схемы параметров.

vocal_genderstring

Предпочтительный вокал; результат не гарантирован.

Значения: m, f

weirdnessnumber

Степень экспериментальности.

Минимум: 0

Максимум: 1

Ответы

200Задача завершена, результат в `data`.

application/json

Схема Job

actionstring

Выполненное действие с аудио.

attempt_countAttemptCountобязательно

channelChannelId | null

Фактический цвет канала запроса: при успехе — канал, который выполнил запрос; пока запрос идёт — канал, которому он уже отправлен; при ошибке — последний вызванный канал. null — запрос ещё не отправлялся ни одному каналу или запись старше каналов. Название и HEX цвета — GET /v1/channels.

completed_atstring | null · date-timeобязательно

Когда задача завершилась; null, пока идёт.

createdinteger · int64обязательно

То же время, что created_at, в unix-секундах — как created у OpenAI.

created_atstring · date-timeобязательно

currencyCurrencyобязательно

dataarray[OutputFile]обязательно

Файлы результата; data[0] — сам результат. У музыкальной модели, которая за запрос даёт два варианта трека, оба — role: result, по порядку. Пустой, пока задача не завершена, и у чата.

durationnumber | null · double

Транскрибация — длительность звука в секундах.

errorErrorBody | nullобязательно

Почему задача не удалась; null, если не провалилась.

idstringобязательно

job_…; у чата — chatcmpl-… из его ответа.

Пример: "job_1a2b3c4d5e6f"

languageLanguageCode | null

Транскрибация — язык записи, код ISO 639-1 (ru, en) у любой модели: названный моделью или, если она его не назвала, из подсказки language запроса. Язык неизвестен — поля нет.

max_price_multiplierMaxPriceMultiplier | nullобязательно

Потолок цены, с которым задача принята: из запроса или из настроек аккаунта на момент приёма. null — без потолка.

modalityModalityобязательно

modelstringобязательно

Пример: "nano-banana-pro"

model_versionstring

Версия музыкальной модели; используйте её при продолжении исходного трека.

objectstringобязательно

Значение: "job"

persona_idstring

ID этой задачи для повторного использования созданной персоны.

priceinteger | null · int64обязательно

Итог в микроединицах currency — фактический объём × цены сработавшего канала на момент приёма; null, пока задача не завершена. У проваленной — 0.

Минимум: 0

resultMusicResult

routingRoutingобязательно

routing_optionsRoutingOptions | nullобязательно

Настройки каналов, с которыми задача принята: из запроса или из настроек аккаунта на момент приёма. null — каналы выбирает Авто-роутинг.

segmentsarray[TranscriptionSegment]

Транскрибация, verbose_json у модели с таймкодами — фразы: предложение или отрезок речи до паузы в секунду и дольше, не длиннее 30 с. Начало фразы — начало её первого слова, конец — конец последнего; одинаково у всех моделей.

statusJobStatusобязательно

textstring | null

Транскрибация — расшифровка; у остальных задач поля нет.

usageJobUsage | nullобязательно

Объём выполненного — токены, символы, секунды; null, где мерить нечего.

voice_idstring

ID этой задачи для повторного использования созданного голоса.

webhookJobWebhook

wordsarray[TranscriptionWord]

Транскрибация — слова с таймкодами, если запрошена детализация по словам.

202Задача принята и выполняется.

application/json

Схема Job

actionstring

Выполненное действие с аудио.

attempt_countAttemptCountобязательно

channelChannelId | null

completed_atstring | null · date-timeобязательно

Когда задача завершилась; null, пока идёт.

createdinteger · int64обязательно

То же время, что created_at, в unix-секундах — как created у OpenAI.

created_atstring · date-timeобязательно

currencyCurrencyобязательно

dataarray[OutputFile]обязательно

durationnumber | null · double

Транскрибация — длительность звука в секундах.

errorErrorBody | nullобязательно

Почему задача не удалась; null, если не провалилась.

idstringобязательно

job_…; у чата — chatcmpl-… из его ответа.

Пример: "job_1a2b3c4d5e6f"

languageLanguageCode | null

max_price_multiplierMaxPriceMultiplier | nullобязательно

modalityModalityобязательно

modelstringобязательно

Пример: "nano-banana-pro"

model_versionstring

Версия музыкальной модели; используйте её при продолжении исходного трека.

objectstringобязательно

Значение: "job"

persona_idstring

ID этой задачи для повторного использования созданной персоны.

priceinteger | null · int64обязательно

Минимум: 0

resultMusicResult

routingRoutingобязательно

routing_optionsRoutingOptions | nullобязательно

segmentsarray[TranscriptionSegment]

statusJobStatusобязательно

textstring | null

Транскрибация — расшифровка; у остальных задач поля нет.

usageJobUsage | nullобязательно

Объём выполненного — токены, символы, секунды; null, где мерить нечего.

voice_idstring

ID этой задачи для повторного использования созданного голоса.

webhookJobWebhook

wordsarray[TranscriptionWord]

Транскрибация — слова с таймкодами, если запрошена детализация по словам.

400Запрос не принят — `Error`; задача провалилась во время ожидания — объект задачи с

Запрос не принят — Error; задача провалилась во время ожидания — объект задачи с error (то же поле, что у Error, поэтому разбирается одним кодом). 503 на плановых работах — Error с кодом maintenance (ответ Maintenance).

application/json

Вариант 1Job

Вариант 2Error

401Нет ключа или ключ недействителен.

application/json

Error

402Баланса не хватает на самый дешёвый канал с учётом запросов, которые ещё

Баланса не хватает на самый дешёвый канал с учётом запросов, которые ещё выполняются (insufficient_balance), или исчерпан лимит трат ключа (key_spend_limit_exceeded) либо участника, которому он выдан (member_spend_limit_exceeded). Повтор не поможет, пока баланс не пополнят, а лимит не начнётся заново или его не поднимут: потолок ключа со spend_limit_reset: none — на всё время ключа.

application/json

Error

403Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. detail[].reason говорит, что именно: requires_api_key, requires_management_key, cabinet_only (только в кабинете), insufficient_role (в allowed — роли, которым можно), not_key_author (секрет ключа открывает только тот, кто его создал).

application/json

Error

404Нет такого объекта у этого аккаунта.

application/json

Error

409Тот же `Idempotency-Key` с другим телом.

application/json

Error

413Тело или файл больше предела (`invalid_input`, `detail[].reason: too_large`) или — только у `POST /v1/files` — загрузки аккаунта заняли квоту (`storage_limit_exceeded`).

application/json

Error

415Тип тела не тот, что принимает метод: `Content-Type: application/json` (у загрузки файла и транскрибации — `multipart/form-data`). В `detail[]` — `{"path": "body", "reason": "unsupported_format"}` и принимаемые типы.

application/json

Error

429Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

application/json

Error

502Запрос не принят — `Error`; задача провалилась во время ожидания — объект задачи с

application/json

Вариант 1Job

Вариант 2Error

503Запрос не принят — `Error`; задача провалилась во время ожидания — объект задачи с

application/json

Вариант 1Job

Вариант 2Error

Платный метод. Запустить в плейграунде модели

Запрос

curl -X POST 'https://api.souz.ai/v1/audio/generations' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "instrumental": true,
  "model": "lyria-3-clip-preview",
  "prompt": "Спокойный лоуфай на пианино для учёбы"
}'

import os
import requests

response = requests.post(
    "https://api.souz.ai/v1/audio/generations",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    json={
        "instrumental": True,
        "model": "lyria-3-clip-preview",
        "prompt": "Спокойный лоуфай на пианино для учёбы",
    },
)
print(response.json())

const response = await fetch("https://api.souz.ai/v1/audio/generations", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "instrumental": true,
    "model": "lyria-3-clip-preview",
    "prompt": "Спокойный лоуфай на пианино для учёбы"
  }),
});
console.log(await response.json());

Ответ

{
  "attempt_count": 1,
  "completed_at": "2026-09-25T12:00:09Z",
  "created": 1758801600,
  "created_at": "2026-09-25T12:00:00Z",
  "currency": "RUB",
  "data": [
    {
      "bytes": 618240,
      "content_type": "image/jpeg",
      "created_at": "2026-09-25T12:00:09Z",
      "expired": false,
      "expires_at": "2026-10-02T12:00:09Z",
      "filename": "souz_nano-banana-pro_9f8e7d6c.jpg",
      "height": 1024,
      "id": "file_9f8e7d6c5b4a",
      "kind": "result",
      "object": "file",
      "role": "result",
      "type": "image",
      "url": "https://media.souz.ai/v1/files/file_9f8e7d6c5b4a/souz_nano-banana-pro_9f8e7d6c.jpg?exp=1759406400&sig=abc",
      "width": 1024
    }
  ],
  "error": null,
  "id": "job_1a2b3c4d5e6f",
  "max_price_multiplier": 2,
  "modality": "image",
  "model": "nano-banana-pro",
  "object": "job",
  "price": 5000000,
  "routing": "cheap",
  "routing_options": null,
  "status": "completed",
  "usage": null
}

{
  "attempt_count": 0,
  "completed_at": null,
  "created": 1758801600,
  "created_at": "2026-09-25T12:00:00Z",
  "currency": "RUB",
  "data": [],
  "error": null,
  "id": "job_1a2b3c4d5e6f",
  "max_price_multiplier": null,
  "modality": "video",
  "model": "seedance-2",
  "object": "job",
  "price": null,
  "routing": "cheap",
  "routing_options": null,
  "status": "queued",
  "usage": null
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient balance",
    "type": "billing_error"
  }
}

{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}