Генерация музыки

Музыка всё ещё производит впечатление чуда: несколько строк о почти забытом лете — и через пару минут готова песня с вокалом, припевом и бриджем. При этом это очень практичный тип генерации. Лицензия на один фон для продуктового видео может стоить дороже месяца экспериментов, а сгенерированный трек создаётся под вашу задачу.

Все операции выполняет публичная модель suno. Поле action выбирает действие: создать песню, продолжить её, сделать кавер, разделить на дорожки, получить синхронизированный текст или сохранить голос как повторно используемую персону.

Что создают с Suno

Простой или custom-режим

Режим выбирает поле custom.

Простой режим (custom отсутствует или равен false) принимает gptDescriptionPrompt длиной до 500 символов. Модель пишет и слова, и аранжировку. Он подходит для фона, mood-трека и любой инструментальной музыки.

Custom-режим (custom: true) принимает текст песни в prompt, жанр и продакшен в tags, название в title. Используйте его, когда слова должны быть точными. Частая ошибка — помещать описание стиля в prompt: в custom это лист с текстом, который модель будет петь.

Как написать промпт стиля

Стилевой промпт — список продакшен-решений:

жанр → инструменты → вокал → темп и настроение.

indie folk, fingerpicked acoustic guitar, brushed drums, warm upright bass,
soft female vocal, 90 bpm, nostalgic and unhurried

• Называйте инструменты: brushed drums, upright bass, Rhodes точнее, чем organic and warm.
• Явно пишите instrumental, если вокал не нужен.
• Указывайте BPM: это помогает подогнать трек к монтажу.
• Ограничьтесь парой стилевых ориентиров, чтобы результат не усреднился.
• В custom-тексте используйте [Verse], [Chorus], [Bridge], [Outro] на отдельных строках.

Рецепты

Органический фон — простой режим music:

Organic downtempo psybient, 95 BPM, didgeridoo and tabla loops, soft analog
pads, forest field recordings, fretless bass, kalimba textures, meditative
dorian A minor, 8 minute slow development, warm earthy production, no vocals
instrumental

Промпт фиксирует темп, инструменты, лад, фактуру и отсутствие вокала.

Песня бренда с вашим текстом:

{
  "custom": true,
  "tags": "upbeat indie pop, jangly electric guitar, handclaps, group vocals, 128 bpm, bright and cheerful",
  "title": "Ship It Friday",
  "prompt": "[Verse]\nWe wrote it down on Monday morning\nHalf a plan and too much coffee\n\n[Chorus]\nShip it Friday, ship it Friday\nNothing's perfect anyway"
}

Делайте строки короткими: длинные фразы приходится втискивать в такт.

Трёхсекундный аудиологотип:

Three-second audio logo: a single bright marimba motif of four notes rising,
one soft synth swell underneath, clean modern, no vocals, ends cleanly

Создайте идею, затем точно обрежьте её через crop и fade-out.

Звуковой эффект — action: "sound":

A heavy wooden door closing in a stone corridor, with a short natural reverb
tail

Та же песня в другом жанре — cover с sourceTaskId:

{
  "action": "cover",
  "sourceTaskId": "019ca881-9503-7270-a560-f00fc2b15785",
  "tags": "slow piano ballad, string section, intimate male vocal, 70 bpm",
  "title": "Ship It Friday (Ballad)"
}

About these samples. Ready-made examples are copied to our own storage only when their source permits reuse. The exact prompt appears above each result, and the original source and license are linked below the media.

Поле action выбирает режим

По умолчанию используется music. Все действия входят в один SunoInputDto, но требования проверяются отдельно:

Источник задаётся через audioId, публичный audioUrl или sourceTaskId вашей предыдущей задачи Suno. sourceTaskId также закрепляет цепочку за тем провайдером, который создал исходник. Полный набор действий (inspo, wav, remaster, crop, fade-in, fade-out, adjust-speed, mashup, boost-style, music-video, midi, bpm) приведён в Моделях музыки.

Отправка запроса

Простой режим:

curl -X POST https://api.api-stock.com/api/v1/generation/create \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "input": {
      "action": "music",
      "gptDescriptionPrompt": "A slow indie folk song about leaving a harbour town at dawn, brushed drums, female vocal"
    }
  }'

Custom-режим:

{
  "model": "suno",
  "input": {
    "action": "music",
    "custom": true,
    "mv": "v5.0",
    "title": "Harbour Lights",
    "tags": "indie folk, brushed drums, warm analog",
    "prompt": "[Verse]\nThe gulls come down before the sun does\n[Chorus]\nAnd the harbour lights go out one by one",
    "makeInstrumental": false
  }
}

В v4.5 и новее prompt допускает 5000 символов, tags — 1000. В старых v3.5 и v4.0 лимиты равны 3000 и 200. makeInstrumental: true отключает вокал и в custom-режиме само удовлетворяет требование промпта.

Чтение результата

Действие music обычно создаёт несколько треков. Обрабатывайте весь массив files, а метаданные читайте из output.tracks. Сохраняйте output.tracks[].audioId вместе с taskId: он выбирает конкретный вариант для extend или stems. URL вроде imageUrl внутри output принадлежат CDN провайдера; в собственное хранилище зеркалируются только элементы files.

Продолжение трека

extend продолжает композицию с обязательной секунды continueAt:

{
  "model": "suno",
  "input": {
    "action": "extend",
    "sourceTaskId": "019ca8d7-6b02-7f31-a1c4-8e5d90b7f2aa",
    "audioId": "b3d1f0a2-77ac-4e19-9c0e-1d2b3f4a5c6d",
    "continueAt": 120,
    "custom": true,
    "prompt": "[Bridge]\nThe tide turns over in the dark",
    "tags": "indie folk, brushed drums"
  }
}

Чтобы продолжить загруженный файл, замените sourceTaskId и audioId на публичный audioUrl.

Кавер на трек

cover перезаписывает источник в новом стиле:

{
  "model": "suno",
  "input": {
    "action": "cover",
    "sourceTaskId": "019ca8d7-6b02-7f31-a1c4-8e5d90b7f2aa",
    "audioId": "b3d1f0a2-77ac-4e19-9c0e-1d2b3f4a5c6d",
    "tags": "synthwave, gated reverb, 1984",
    "title": "Harbour Lights (Synth)"
  }
}

Разделение на stems

stems извлекает одну дорожку, stems-all разделяет композицию на двенадцать категорий. stemType может быть lead_vocal, backing_vocals, drum_kit, bass, piano, electric_guitar и другими.

{
  "model": "suno",
  "input": {
    "action": "stems",
    "sourceTaskId": "019ca8d7-6b02-7f31-a1c4-8e5d90b7f2aa",
    "audioId": "b3d1f0a2-77ac-4e19-9c0e-1d2b3f4a5c6d",
    "stemType": "drum_kit"
  }
}

Действия, возвращающие данные

lyrics, timestamped-lyrics, boost-style, midi и bpm завершаются без files: результат находится в output.

{
  "model": "suno",
  "input": {
    "action": "lyrics",
    "prompt": "A song about leaving a harbour town at dawn",
    "mv": "remi-v1"
  }
}

Структура output следует формату провайдера, поэтому читайте её защитно. timestamped-lyrics требует sourceTaskId и возвращает временные метки слов.

Голоса и персоны

voice создаёт повторно используемую голосовую персону из voiceAudioUrl или предыдущего sourceTaskId. Сохраните полученный идентификатор из output и передавайте его в следующих задачах, когда нужен согласованный вокал. Используйте только аудио, на которое у вас есть права и согласие говорящего.

Полный цикл

После create сохраните data.taskId. Проверяйте GET /api/v1/task/status/{taskId} с интервалом около 10 секунд или передайте верхнеуровневый webhook. При finished скачайте все элементы files и сохраните audioId из output; при failed покажите errorMessage — средства уже возвращены.

Если генерация не удалась

• В simple-режиме нужен gptDescriptionPrompt; в custom — prompt, если не задан makeInstrumental: true.
• Для extend обязателен continueAt и один источник.
• Stateful-действия должны ссылаться на вашу успешную задачу Suno.
• finished без files допустим для действий, возвращающих данные.
• Обычные 400 исправляются изменением тела, а не повтором запроса.

Следующие шаги

• Модели музыки — полный набор действий и полей.
• Статус задачи — чтение files и output.
• Вебхуки, файлы и ошибки.