API zum Herunterladen und Anhören von Song-Medien

Aktualisiert am 2026-09-18 · Suno-API-Team

Beschreibung des Endpunkts

Diese Gruppe von Endpunkten trennt „eine Medienadresse holen“ von „die Datei tatsächlich herunterladen“:

• Um eine direkt abspielbare oder herunterladbare Adresse zu erhalten (etwa für den eigenen Player oder zum Kopieren in einen Objektspeicher): POST /api/music/download-url verwenden, oder das GET /api/music/download, das bereits in Antworten enthalten ist.
• Damit der Browser die Datei direkt auf die Festplatte speichert: POST /api/music/download-file (einzelne Datei) oder POST /api/music/download-all (Paket) verwenden.
• Wenn der Song noch generiert wird und Sie zuerst hineinhören möchten: POST /api/music/generation-stream-url verwenden.

Abrechnung: Alles kostenlos. Herunterladen und Anhören lesen nur Medien, die die Plattform bereits hostet; sie rufen Suno nicht auf und werden nicht berechnet.

Empfohlenes Modell: suno-v6. Verfügbar sind suno-v6, suno-v6-wild und suno-v6-mini.

Authentifizierung

Unterstützte Medientypen (kind)

1) Medienadresse abrufen

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 dient der Wiedergabe oder dem eigenen Kopieren; nav_url trägt Content-Disposition: attachment und eignet sich zum direkten Einfügen in die Adressleiste des Browsers zum Herunterladen (nützlich, wenn einige mobile Browser den Blob-Download nicht unterstützen).

⚠️ Gültigkeit der Adresse: 7 Tage — Datei rechtzeitig kopieren

url / nav_url verweisen auf den Objektspeicher der Plattform und laufen standardmäßig nach 7 Tagen ab (die Dateien werden zurückgeholt und die alte Adresse liefert 404). Kopieren Sie sie innerhalb dieser 7 Tage in Ihren eigenen Speicher.

Nach dem Ablauf muss der Song nicht neu generiert werden: rufen Sie POST /api/music/download-url erneut auf (oder übergeben Sie refresh: true), um neue gültige Adressen für diesen Song zu erhalten. Diese Endpunktgruppe ist kostenlos und verursacht keine zusätzlichen Kosten.

2) Eine einzelne Datei direkt herunterladen

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

Der Antwort-Body ist ein Dateistream (kein JSON) und Content-Disposition enthält bereits den Dateinamen. Songtext und zeitgestempelter Songtext lassen sich nur mit diesem Endpunkt abrufen (download-url liefert nur Medienadressen, keinen Songtext). Die .lrc-Datei wird derzeit nur für einige Songs unterstützt; kommt success:false zurück, erzeugen Sie die .lrc selbst mit der API für zeitgestempelte Songtexte wie im nächsten Abschnitt, und wiederholen Sie den Aufruf nicht.

Zeitgestempelte Songtexte (.lrc) abrufen

Empfohlen sind zwei Schritte, die für jeden Song funktionieren:

Schritt 1: die Wort-für-Wort-Timeline holen (kostenlos)

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

Die Antwort ist direkt ein Array (ohne data-Wrapper); jedes Element sieht so aus: {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word enthält bereits Zeilenumbrüche, lässt sich also zeilenweise aufteilen; zu Feldbedeutungen, dem Herausfiltern von Instrumentalpassagen und weiteren Hinweisen siehe „Felder“ und „Hinweise zur Verwendung“ der API für zeitgestempelte Songtexte.

Schritt 2: die .lrc selbst aus start_s bauen (Zeitformat [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 lädt die serverseitig erzeugte .lrc ebenfalls direkt herunter, aber derzeit werden nur einige Songs unterstützt: kommt success:false zurück, erzeugen Sie sie selbst wie oben — kein erneuter Versuch nötig, und die Abrechnung ist davon nicht betroffen.

3) Paket-Download

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

Verwenden Sie entweder song_id (einzeln) oder song_ids (Stapel, bis zu 50 Einträge). Der Antwort-Body ist ein ZIP-Dateistream.

4) Stabile Download-Adresse

GET /api/music/download?song_id=<id>&kind=<kind> ist der Download-Einstieg, der direkt in Song-Antworten enthalten ist. Er akzeptiert sowohl einen API-Schlüssel als auch eine Browser-Sitzung, verhält sich wie download-file und eignet sich zum Festverdrahten in einen Client oder einen Drittanbieter-Player.

5) Reinhören während der Generierung

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

Ein playable_until_completed von true bedeutet, dass dies eine temporäre Reinhöradresse für einen noch generierenden Song ist; wechseln Sie zur endgültigen Adresse, sobald der Song fertig ist. Schlägt ein Song fehl, trägt dieser Eintrag ein error-Feld und die übrigen Songs kommen wie gewohnt zurück.

Hinweise

• Alle Endpunkte liefern ausschließlich von der Plattform gehostete Medienadressen; sie liefern niemals Sunos verschlüsselte Quelle oder eine temporär signierte Adresse.
• Die Adressen sind nicht dauerhaft — kopieren Sie die Dateien selbst, wenn Sie sie langfristig behalten wollen; nutzen Sie download-file, wenn Sie die Originaldatei auf der Festplatte brauchen.
• Das MIDI eines Stems setzt voraus, dass die Trennung dieses Stems abgeschlossen ist, sonst wird ein Fehler zurückgegeben.