API скачивания и прослушивания медиа песен

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

Описание эндпоинта

Эта группа эндпоинтов разделяет «получить адрес медиа» и «реально скачать файл»:

• Нужен адрес, который можно сразу воспроизвести или скачать (например, вставить в свой плеер или перенести в объектное хранилище): используйте POST /api/music/download-url или уже присутствующий в ответах GET /api/music/download.
• Нужно, чтобы браузер сам сохранил файл на диск: используйте POST /api/music/download-file (один файл) или POST /api/music/download-all (архив).
• Песня ещё генерируется и хочется послушать заранее: используйте POST /api/music/generation-stream-url.

Оплата: всё бесплатно. Скачивание и прослушивание только читают уже размещённые на платформе медиа, не обращаются к Suno и не тарифицируются.

Рекомендуемая модель: suno-v6. Доступны suno-v6, suno-v6-wild и suno-v6-mini.

Аутентификация

Поддерживаемые типы медиа (kind)

1) Получение адреса медиа

curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url предназначен для воспроизведения или самостоятельного копирования; nav_url несёт Content-Disposition: attachment и подходит для вставки прямо в адресную строку браузера для скачивания (когда мобильные браузеры не поддерживают скачивание через blob).

⚠️ Срок действия адреса: 7 дней — сохраните файл вовремя

url / nav_url указывают на объектное хранилище платформы и по умолчанию истекают через 7 дней (файлы изымаются, старый адрес возвращает 404). Скопируйте их в собственное хранилище в течение этих 7 дней.

После истечения не нужно заново генерировать песню: повторно вызовите POST /api/music/download-url (или передайте refresh: true), чтобы получить новые действующие адреса этой песни. Сама эта группа эндпоинтов бесплатна и не добавляет списаний.

2) Прямое скачивание одного файла

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}' \
  -o song.mp3

Тело ответа — поток файла (не JSON), а Content-Disposition уже содержит имя файла. Текст песни и текст с таймкодами можно получить только этим эндпоинтом (download-url возвращает лишь адреса медиа, но не текст). Файл .lrc сейчас поддерживается лишь для части песен; если вернулось success:false, соберите .lrc сами через API текста с таймкодами так, как показано в следующем разделе, и не повторяйте запрос.

Как получить текст с таймкодами (.lrc)

Рекомендуются два шага, они подходят для любой песни:

Шаг 1: получить таймлайн по словам (бесплатно)

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

Ответ — сразу массив (без обёртки data); каждый элемент выглядит так: {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word уже содержит переводы строк, поэтому его можно разбить по строкам; значения полей, отсеивание инструментальных фрагментов и прочие оговорки см. в разделах «Поля» и «Замечания по использованию» API текста с таймкодами.

Шаг 2: собрать .lrc самим из start_s (формат времени [mm:ss.cc])

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc тоже скачивает созданный сервером .lrc напрямую, но сейчас поддерживается лишь часть песен: если вернулось success:false, соберите файл сами способом выше — повторять запрос не нужно, на тарификацию это не влияет.

3) Пакетная загрузка

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

Используйте либо song_id (одна песня), либо song_ids (пакет, до 50 записей). Тело ответа — ZIP-поток.

4) Стабильный адрес загрузки

GET /api/music/download?song_id=<id>&kind=<kind> — точка входа для скачивания, которая прямо выдаётся в ответах по песне. Она принимает и API-ключ, и сессию входа, ведёт себя как download-file и подходит для жёсткой привязки в клиенте или стороннем плеере.

5) Прослушивание во время генерации

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

playable_until_completed равное true означает, что это временный адрес прослушивания для ещё генерирующейся песни; после завершения песни перейдите на постоянный адрес. Если одна песня не удалась, у этого элемента будет поле error, а остальные песни вернутся как обычно.

Примечания

• Все эндпоинты возвращают только адреса медиа, размещённых платформой; они никогда не возвращают зашифрованный источник Suno или временно подписанный адрес.
• Адреса не вечны: если нужно хранить файлы долго, копируйте их сами; когда нужен исходный файл на диске, используйте download-file.
• MIDI дорожки требует, чтобы разделение этой дорожки было завершено, иначе возвращается ошибка.