Документация

Задачи генерации аудио

Обновлено: 2026-08-30

Обзор API

Генерация музыки Suno и FlowMusic выполняется асинхронно:

Вызов POST /v1/audios/tasks отправки задачи
Сохраните публичный ID задачи из ответа
Вызов GET /v1/tasks/{task_id} для проверки статуса и получения результата

Base URL: https://api.rokoapi.com/v1, все запросы должны содержать заголовок Authorization: Bearer $API_KEY.

Доступные модели

suno-v3.5
suno-v4
suno-v4.5
suno-v4.5-all
suno-v4.5-plus
suno-v5
suno-v5.5
flowmusic-lyria-3-pro
flowmusic-lyria-3.5

Фактический список доступных моделей определяется по /v1/models и группе, к которой относится ключ API.

Генерация с FlowMusic Lyria

FlowMusic принимает только поля, опубликованные в каталоге моделей. Укажите хотя бы одно из полей prompt или metadata.lyrics; не добавляйте параметры, отсутствующие в метаданных модели.

{
  "model": "flowmusic-lyria-3.5",
  "prompt": "кинематографичная эмбиент-музыка с тёплыми струнными и мягким фортепиано",
  "duration": 30,
  "metadata": {
    "lyrics": "[Verse]\nNeon rain falls softly tonight",
    "title": "Neon Rain",
    "bpm": 120,
    "seed": "42"
  }
}

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

curl https://api.rokoapi.com/v1/audios/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5.5",
    "action": "generate",
    "mode": "easy",
    "prompt": "Бодрая летняя поп-песня с женским вокалом и яркими гитарами"
  }'

action Если параметр опущен, по умолчанию используется generate, mode Если параметр опущен, по умолчанию используется easy.

Расширенный режим

{
  "model": "suno-v5.5",
  "action": "generate",
  "mode": "advanced",
  "lyrics": "[Verse]\nWalking through the neon rain...",
  "style": "synth-pop, female vocal, 120 bpm",
  "title": "Neon Rain",
  "instrumental": false
}

advanced В режимеprompt, lyrics, style необходимо указать хотя бы один из параметров. При установке lyrics_model также обязательно указать prompt.

Продолжение фрагмента

{
  "model": "suno-v5.5",
  "action": "extend",
  "continue_clip_id": "clip_123",
  "continue_at": 90,
  "prompt": "Перейти к более мощному припеву"
}

extend Для параметра continue_clip_id и неотрицательного значения continue_at.

Ответ на отправку

При успешной отправке возвращается HTTP 202: ```json { “id”: “task_public_id”, “object”: “audio.generation.task”, “status”: “queued”, “upstream”: “Suno Task API” }


Для последующих запросов всегда используйте публичный `id`из ответа, а не внутренний ID задачи провайдера.

## Запрос статуса задачи

```bash
curl https://api.rokoapi.com/v1/tasks/task_public_id \
  -H "Authorization: Bearer $API_KEY"

Типичные статусы: queued, in_progress, completed и failed. После завершения задачи в результате будет указан URL сгенерированного аудио. Рекомендуется постепенно увеличивать интервал опроса, чтобы избежать частых запросов.

Архивирование результатов и адреса медиафайлов

Если на сервере включено архивирование медиа, успешное выполнение задачи не означает, что адрес файла стабилизирован. Клиенту следует продолжать опрос, пока archive_status не станет ready(или partialпри частичном успехе), после чего можно сохранить assets[].url.

После архивирования аудио, обложки, видео и тексты песен переносятся на CDN платформыhttps://cdn.rokoapi.com, возвращаются публичные HTTPS-адреса, которые невозможно угадать, и доступ к ним возможен без API Token.

Срок хранения

Архивированные медиафайлы хранятся по умолчанию 24 часа, после чего объекты удаляются, а статус соответствующих активов становится expired.
Срок истечения для каждого актива указан в assets[].expires_at(Unix-время в секундах).
Если клиенту требуется долгосрочное использование, необходимо скачать и сохранить файлы в собственном хранилище в течение 24 часов; не используйте адреса CDN платформы как постоянные ссылки.
archive_status становится expired после чего исходный assets[].url будет недоступен.

Пример ответа на запрос:

{
  "code": "success",
  "data": {
    "task_id": "task_public_id",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://cdn.rokoapi.com/media/2026/07/abcdef.mp3",
    "archive_status": "ready",
    "assets": [
      {
        "output_id": "clip-1",
        "kind": "audio",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/abcdef.mp3",
        "content_type": "audio/mpeg",
        "size": 3456789,
        "expires_at": 1753862400,
        "status": "ready"
      },
      {
        "output_id": "clip-1",
        "kind": "cover",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/coverxyz.jpg",
        "content_type": "image/jpeg",
        "expires_at": 1753862400,
        "status": "ready"
      },
      {
        "output_id": "clip-1",
        "kind": "lyrics",
        "title": "Neon Rain",
        "url": "https://cdn.rokoapi.com/media/2026/07/lyricsxyz.txt",
        "content_type": "text/plain; charset=utf-8",
        "expires_at": 1753862400,
        "status": "ready"
      }
    ]
  }
}

Примечание:

archive_status: pending / processing / ready / partial / failed / expired
assets: одна задача может содержать несколько клипов, каждый из которых может включать audio, cover, video, lyrics
result_url: публичный URL первого архивированного аудиофайла; до завершения архивирования может оставаться временным URL провайдера
assets[].expires_at: предполагаемое время удаления файла; по умолчанию — через 24 часа после завершения архивирования
Публичные URL медиафайлов не поддаются угадыванию и не требуют токена платформы; по умолчанию хранятся 24 часа, после чего удаляются**
Нижестоящим сервисам следует сохранять только архивированные публичные URL (и перемещать их до истечения срока), не полагаясь на временные адреса CDN провайдера

Рекомендации по опросу:

# После успеха продолжать опрос до archive_status=ready
curl https://api.rokoapi.com/v1/tasks/task_public_id \
  -H "Authorization: Bearer $API_KEY"

Параметры

Параметр	Тип	Описание
`model`	string	ID модели Suno, обязателен
`action`	string	`generate` или `extend`
`mode`	string	Режим генерации:`easy` или `advanced`
`prompt`	string	Описание песни на естественном языке
`lyrics`	string	Пользовательские тексты
`style`	string	Описание стиля, настроения, инструментов и т. д.
`instrumental`	boolean	Генерировать ли инструментальную музыку
`title`	string	Название песни
`vocal_gender`	string	Необязательное предпочтение голоса
`continue_clip_id`	string	ID исходного клипа для продолжения
`continue_at`	number	Продолжение с указанной секунды исходного клипа, не может быть отрицательным
`timeout_ms`	integer	Таймаут задачи провайдера, диапазон 10 000–7 200 000 мс

Тарификация

Все версии Suno по умолчанию тарифицируются за вызов; текущая цена по умолчанию в коде составляет $0.06 за вызов. $0.06. Цены на модели и множители групп в консоли могут переопределять значения по умолчанию; ориентируйтесь на данные на странице тарифов

Отличия от старого API Suno

/v1/audios/tasks использует suno-v* ID модели и единый интерфейс запроса задач. Старая версия /suno/submit использует suno_music, suno_lyrics и другие имена моделей; эти два набора API и имена моделей нельзя смешивать.

Частые ошибки

400: неверный путь, action, mode или обязательный параметр
403: у группы ключа нет прав на модель или недостаточно средств
404: ID задачи не существует или модель не включена в доступных каналах
502: провайдер вернул недействительный ответ или сервис задач временно недоступен