API de descărcare și ascultare a conținutului media al pieselor

Actualizat pe 2026-09-18 · echipa Suno-API

Descrierea endpoint-ului

Acest grup de endpoint-uri separă „obținerea unei adrese media” de „descărcarea efectivă a fișierului”:

• Pentru o adresă pe care o poți reda sau descărca direct (de exemplu pentru propriul player sau pentru a o copia în stocare obiect): folosește POST /api/music/download-url, sau GET /api/music/download care apare deja în răspunsuri.
• Pentru ca browserul să salveze fișierul direct pe disc: folosește POST /api/music/download-file (un singur fișier) sau POST /api/music/download-all (pachet).
• Dacă piesa încă se generează și vrei să asculți mai întâi: folosește POST /api/music/generation-stream-url.

Facturare: Totul este gratuit. Descărcarea și ascultarea citesc doar conținut media pe care platforma îl găzduiește deja; nu apelează Suno și nu se facturează.

Model recomandat: suno-v6. Poți folosi suno-v6, suno-v6-wild sau suno-v6-mini.

Autentificare

Tipuri media acceptate (kind)

1) Obținerea unei adrese media

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 servește la redare sau la copierea pe cont propriu; nav_url poartă Content-Disposition: attachment și se pretează la lipirea direct în bara de adrese a browserului pentru descărcare (util când unele browsere mobile nu acceptă descărcarea prin blob).

⚠️ Valabilitatea adresei: 7 zile — copiază fișierul la timp

url / nav_url indică spre stocarea obiect a platformei și expiră implicit după 7 zile (fișierele sunt recuperate și adresa veche returnează 404). Copiază-le în propria stocare în aceste 7 zile.

După expirare nu este nevoie să regenerezi piesa: apelează din nou POST /api/music/download-url (sau trimite refresh: true) pentru a obține adrese noi valide pentru acea piesă. Acest grup de endpoint-uri este gratuit și nu adaugă costuri.

2) Descărcarea directă a unui singur fișier

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

Corpul răspunsului este un flux de fișier (nu JSON), iar Content-Disposition conține deja numele fișierului. Versurile și versurile cu marcaje de timp se obțin doar cu acest endpoint (download-url returnează doar adrese media, nu versuri). Fișierul .lrc este momentan acceptat doar pentru unele piese; dacă returnează success:false, generează .lrc singur cu API de versuri cu marcaje de timp conform secțiunii următoare, fără a reîncerca.

Cum obții versuri cu marcaje de timp (.lrc)

Se recomandă doi pași, valabili pentru orice piesă:

Pasul 1: obține cronologia cuvânt cu cuvânt (gratuit)

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

Răspunsul este direct un array (fără înveliș data); fiecare element arată astfel: {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word conține deja linii noi, așa că îl poți împărți pe rânduri; pentru semnificația câmpurilor, filtrarea pasajelor instrumentale și alte atenționări vezi „Câmpuri” și „Note de utilizare” din API de versuri cu marcaje de timp.

Pasul 2: construiește .lrc singur din start_s (format de timp [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 descarcă direct și .lrc-ul generat de server, dar momentan sunt acceptate doar unele piese: dacă returnează success:false, generează-l singur ca mai sus — nu e nevoie de reîncercare și facturarea nu este afectată.

3) Descărcare în pachet

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

Folosește song_id (una singură) sau song_ids (lot, până la 50 de intrări). Corpul răspunsului este un flux ZIP.

4) Adresă de descărcare stabilă

GET /api/music/download?song_id=<id>&kind=<kind> este punctul de intrare pentru descărcare oferit direct în răspunsurile despre piesă. Acceptă atât o cheie API, cât și o sesiune de browser, se comportă la fel ca download-file și este potrivit pentru a fi fixat într-un client sau într-un player terț.

5) Ascultare în timpul generării

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
      }
    ]
  }
}

Un playable_until_completed egal cu true înseamnă că este o adresă temporară de ascultare pentru o piesă în curs de generare; treci la adresa definitivă după ce piesa se termină. Dacă o piesă eșuează, acea intrare are un câmp error, iar celelalte piese se returnează normal.

Note

• Toate endpoint-urile returnează doar adrese media găzduite de platformă; nu returnează niciodată sursa criptată a Suno sau o adresă semnată temporar.
• Adresele nu sunt permanente: copiază fișierele singur dacă vrei să le păstrezi pe termen lung; folosește download-file când ai nevoie de fișierul original pe disc.
• MIDI-ul unui stem necesită ca separarea acelui stem să fie încheiată, altfel se returnează o eroare.