API запроса песен и истории

Обновлено 2026-09-18 · команда Suno-API

На этой странице три бесплатных эндпоинта запроса:

Если вы использовали режим квитанции-приёмки (accept_mode=async) на эндпоинте генерации, у вас на руках номер квитанции, а не ID песни. Отслеживайте прогресс через GET /api/music/requests/{request_id} и возвращайтесь к эндпоинтам этой страницы, когда получите настоящий song_id. См. «Режим квитанции-приёмки» в API генерации в простом режиме.

Аутентификация и охват данных

Все три эндпоинта используют один и тот же ключ API:

Authorization: Bearer YOUR_API_KEY

История песен изолирована по user_id, которому принадлежит ключ API. Несколько ключей, созданных под одним основным аккаунтом, могут читать историю этого аккаунта, но не песни другого пользователя или другого аккаунта подсайта.

Эндпоинты истории возвращают только реально созданные песни. Исключены:

• записи-заглушки генерации, начинающиеся с pending:;
• загрузки исходного аудио и записи улучшенной загрузки;
• побочные результаты: разделение вокала/аккомпанемента, стемы и т. п.;
• песни других пользователей или аккаунтов подсайтов.

1. Запрос статуса генерации

Запрашивает текущий статус и итоговый результат для одного или нескольких ID песен.

Эндпоинт: POST /api/music/query

Оплата: бесплатно.

Headers

Параметры тела

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

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Пример ответа

[
  {
    "song_id": "clip_id_1",
    "song_title": "Название песни",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Текст песни",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Замечания о совместимости

В старой документации song_ids может быть указан как массив. Сейчас рекомендуется строка с запятыми — так эндпоинт и вызывается на самом деле.

song_ids должен содержать реальные ID песен. ID-заглушка, начинающаяся с pending:, не является итоговым song_id и здесь не работает; если запрашивать только заглушки, может вернуться пустой массив [].

Значения model, model_version или платформенного model_name в ответе могут быть историческими. Новым задачам следует использовать suno-v6, suno-v6-wild или suno-v6-mini; от suno-v2 до suno-v5-5 выведены из эксплуатации, и появление этих названий в истории не означает, что модель всё ещё можно отправлять.

Пока задача в состоянии pending, submitted или processing, поля audio_url, video_url и cover_url могут быть пустыми — это нормально для незавершённой задачи. Не делайте вывод об ошибке только из пустого адреса; ориентируйтесь на status и запросите снова, когда статус станет завершённым. Только если статус завершён, а адреса по-прежнему пусты, стоит связаться с поддержкой и указать song_id.

⚠️ Адреса аудио живут 7 дней — перенесите файлы вовремя

Возвращаемые здесь audio_url, video_url (и другие адреса медиа, например WAV) отдаются из объектного хранилища платформы и по умолчанию истекают через 7 дней: файлы перерабатываются, и старый адрес возвращает 404.

• В течение этих 7 дней перенесите файлы в собственное хранилище; не считайте адрес долговременной ссылкой.
• Истёкший адрес не требует повторной генерации песни и не оплачивается заново: вызовите этот эндпоинт (POST /api/music/query) снова, чтобы получить свежий действующий адрес этой песни.

2. Запрос истории песен аккаунта

Список песен, созданных основным аккаунтом текущего ключа API. Подходит для собственного списка песен, селектора или страницы истории.

Эндпоинт: GET /api/music/songs

Оплата: бесплатно.

Параметры запроса

Результаты упорядочены по created_at и внутреннему ID записи по убыванию, поэтому порядок постраничного вывода стабилен.

Как найти отправку, которая ушла в тайм-аут: эндпоинты генерации не дают промежуточного ответа до приёма. Если клиент ушёл в тайм-аут или соединение оборвалось при отправке, заказ мог уже быть принят и генерироваться. Загляните в этот эндпоинт (сначала новые): принятые песни появляются в списке как обычно. Отправляйте повторно только убедившись, что песни действительно нет, чтобы не заплатить дважды. См. «Время ожидания и настройка тайм-аута» в Обзоре нового API.

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

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример ответа

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Город в ночи",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Поля ответа

Эндпоинт списка не возвращает промпты, поля оплаты, информацию об аккаунте или исходные ответы. За промптами и параметрами генерации обращайтесь к эндпоинту деталей песни.

3. Запрос параметров генерации

Запрашивает промпт, стиль, модель и исходную песню, которые платформа сохранила при создании песни.

Эндпоинт: GET /api/music/songs/:song_id

Оплата: бесплатно.

Доступны только песни основного аккаунта текущего ключа API. Песни других пользователей или аккаунтов подсайтов единообразно трактуются как «песня не найдена».

Параметр пути

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

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример ответа

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Город в ночи",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "городские улицы после дождя, текст о новой встрече",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Город в ночи",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

Поля parameters

Поле prompt_view (просмотр промпта, добавлено 2026-09-28)

prompt_view — нормализованная структура специально для «просмотра промпта»: она раскладывает данные по фиксированным разделам в зависимости от типа генерации, так что клиенту больше не нужно решать, какое поле показывать. Это чисто добавочное поле — старые поля (parameters, parameter_retention) сохраняют имена и смысл, а клиенты, которые не разбирают новое поле, не затронуты вовсе.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Расширенный режим",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Четыре утра#701f37", "title_base": "Четыре утра", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "…", "user_text_kind": "lyrics",
    "user_style": "гуочао-электроника, глубокий саб-бас, ретро-синтезатор",
    "style_tags": "гуочао-электроника, глубокий саб-бас, ретро-синтезатор",
    "style_source": "user", "lyrics": "…",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Поля, которые могут появиться в extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, а также группа звуковых эффектов sound_type / sound_bpm / sound_key / sound_loop. Пустые значения не возвращаются никогда.

Три правила отображения (следуйте им, а не догадывайтесь):

1. Различайте источник стиля: при style_source=suno_derived показывайте «стиль (выведен Suno из вашего описания)» и никогда «ваш стиль»;
2. Внутренние промпты не появляются: голосовые кавер-типы возвращают только введённые пользователем 【требования к стилю】/【требования к каверу】; фиксированный каркас, который мы собираем для модели, не появляется ни в одном поле (исторические данные очищены так же);
3. Не угадывайте отсутствующие параметры: если в extended чего-то нет, значит тогда это не записали — объясните причину через retention.

О сохранении параметров

parameter_retention разделяет «пустое значение передали явно» и «поле исторически не сохранялось»:

• core_parameters_available: существует ли основная запись задачи; при корректном запросе деталей обычно true;
• extended_parameters_available: найдена ли связанная запись расширенной музыкальной задачи;
• sources: из каких таблиц данных взята эта информация;
• unavailable_fields: поля, которые нельзя надёжно восстановить из истории; они возвращают null внутри parameters.

Обычные исторические песни обычно хранят промпт, стиль, текущее название, модель, тип генерации и исходную песню, но не сохраняли все расширенные параметры отдельно. Платформа никогда не угадывает отсутствующие значения по generation_type.

Некоторые расширенные музыкальные задачи хранят также исходный промпт, стиль, название, модель и дополнительно custom_mode, negative_tags, vocal_gender, style_weight и weirdness_constraint. Даже при наличии расширенной записи instrumental, lyrics_mode и wait_audio могут остаться невосстановимыми.

Названия песен пользователь может переименовать позже. Если обычная историческая задача не сохранила отдельного исходного названия, parameters.title может быть текущим названием; при наличии расширенной записи приоритет отдаётся исходному названию генерации из неё.

Не найдено или нет прав

Бизнес-ошибки используют единый конверт ответа. Если песня не существует или не принадлежит текущему аккаунту:

{
  "success": false,
  "message": "song not found"
}

Эта бизнес-ошибка сейчас возвращается с HTTP 200, поэтому судите о результате по полю success. Отсутствующий, недействительный, истёкший или отключённый ключ API возвращает HTTP 401.

Безопасность

Эндпоинты истории и деталей никогда не возвращают:

• ключи API и ID токенов;
• поля квот, оплаты и возвратов;
• информацию об аккаунте и исходные ответы;
• внутренние ключи объектного хранилища;
• административные ошибки и ошибки внутренних ресурсов.