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 доріжки потребує завершеного розділення цієї доріжки, інакше повертається помилка.