API pobierania i odsłuchu mediów utworów

Zaktualizowano 2026-09-18 · zespół Suno-API

Opis punktu końcowego

Ta grupa punktów końcowych rozdziela „pobranie adresu mediów” od „rzeczywistego pobrania pliku”:

• Aby uzyskać adres, który można od razu odtworzyć lub pobrać (np. do własnego odtwarzacza albo skopiowania do magazynu obiektów): użyj POST /api/music/download-url lub podanego już w odpowiedziach GET /api/music/download.
• Aby przeglądarka zapisała plik na dysku: użyj POST /api/music/download-file (pojedynczy plik) lub POST /api/music/download-all (pakiet).
• Jeśli utwór wciąż się generuje, a chcesz go najpierw odsłuchać: użyj POST /api/music/generation-stream-url.

Rozliczenie: Wszystko bezpłatne. Pobieranie i odsłuch tylko czytają media już hostowane przez platformę, nie wywołują Suno i nie są rozliczane.

Zalecany model: suno-v6. Dostępne są suno-v6, suno-v6-wild i suno-v6-mini.

Uwierzytelnianie

Obsługiwane typy mediów (kind)

1) Pobieranie adresu mediów

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 służy do odtwarzania lub samodzielnego skopiowania; nav_url zawiera Content-Disposition: attachment i nadaje się do wklejenia wprost w pasek adresu przeglądarki w celu pobrania (przydatne, gdy niektóre przeglądarki mobilne nie obsługują pobierania przez blob).

⚠️ Ważność adresu: 7 dni — skopiuj plik na czas

url / nav_url wskazują na magazyn obiektów platformy i domyślnie wygasają po 7 dniach (pliki są odzyskiwane, a stary adres zwraca 404). Skopiuj je do własnego magazynu w ciągu tych 7 dni.

Po wygaśnięciu nie trzeba generować utworu od nowa: wywołaj ponownie POST /api/music/download-url (lub przekaż refresh: true), aby otrzymać nowe ważne adresy tego utworu. Ta grupa punktów końcowych jest bezpłatna i nie powoduje dodatkowych opłat.

2) Bezpośrednie pobieranie pojedynczego pliku

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

Treścią odpowiedzi jest strumień pliku (nie JSON), a Content-Disposition zawiera już nazwę pliku. Tekst utworu i tekst ze znacznikami czasu można pobrać wyłącznie tym punktem końcowym (download-url zwraca tylko adresy mediów, nie tekst). Plik .lrc jest obecnie obsługiwany tylko dla części utworów; jeśli zwróci success:false, zbuduj .lrc samodzielnie za pomocą API tekstu ze znacznikami czasu zgodnie z następną sekcją, bez ponawiania.

Jak pobrać tekst ze znacznikami czasu (.lrc)

Zalecane są dwa kroki, działające dla każdego utworu:

Krok 1: pobierz oś czasu słowo po słowie (bezpłatnie)

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"}'

Odpowiedź to zwykła tablica (bez opakowania data); każdy element wygląda tak: {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word zawiera już znaki nowej linii, więc można go podzielić na linie; znaczenie pól, odfiltrowywanie fragmentów instrumentalnych i inne uwagi znajdziesz w sekcjach „Pola” i „Uwagi dotyczące użycia” API tekstu ze znacznikami czasu.

Krok 2: zbuduj .lrc samodzielnie z start_s (format czasu [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 również pobiera bezpośrednio .lrc wygenerowany przez serwer, ale obecnie obsługiwane są tylko niektóre utwory: jeśli zwróci success:false, zbuduj plik samodzielnie jak wyżej — ponawianie nie jest potrzebne i nie wpływa na rozliczenie.

3) Pobieranie w pakiecie

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

Użyj song_id (pojedynczy) albo song_ids (partia, do 50 pozycji). Treścią odpowiedzi jest strumień ZIP.

4) Stabilny adres pobierania

GET /api/music/download?song_id=<id>&kind=<kind> to punkt wejścia do pobierania podany wprost w odpowiedziach o utworze. Przyjmuje zarówno klucz API, jak i sesję logowania, działa tak samo jak download-file i nadaje się do wpisania na stałe w kliencie lub zewnętrznym odtwarzaczu.

5) Odsłuch w trakcie generowania

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 równe true oznacza tymczasowy adres odsłuchu utworu, który wciąż się generuje; po zakończeniu utworu przejdź na adres stały. Jeśli jeden utwór zawiedzie, ten element będzie miał pole error, a pozostałe utwory wrócą jak zwykle.

Uwagi

• Wszystkie punkty końcowe zwracają wyłącznie adresy mediów hostowanych przez platformę; nigdy nie zwracają zaszyfrowanego źródła Suno ani tymczasowo podpisanego adresu.
• Adresy nie są trwałe — jeśli chcesz zachować pliki na dłużej, skopiuj je samodzielnie; gdy potrzebujesz oryginalnego pliku na dysku, użyj download-file.
• MIDI ścieżki wymaga zakończonego rozdzielania tej ścieżki, inaczej zwracany jest błąd.