API voor het downloaden en beluisteren van nummer-media

Bijgewerkt op 2026-09-18 · Suno-API-team

Beschrijving van het endpoint

Deze groep endpoints scheidt "een media-adres ophalen" van "het bestand echt downloaden":

• Voor een adres dat u direct kunt afspelen of downloaden (bijvoorbeeld voor uw eigen speler of om naar objectopslag te kopiëren): gebruik POST /api/music/download-url, of de GET /api/music/download die al in antwoorden zit.
• Om de browser het bestand direct op schijf te laten opslaan: gebruik POST /api/music/download-file (één bestand) of POST /api/music/download-all (pakket).
• Als het nummer nog wordt gegenereerd en u eerst wilt meeluisteren: gebruik POST /api/music/generation-stream-url.

Facturering: Allemaal gratis. Downloaden en beluisteren lezen alleen media die het platform al host; ze roepen Suno niet aan en worden niet gefactureerd.

Aanbevolen model: suno-v6. Beschikbaar zijn suno-v6, suno-v6-wild en suno-v6-mini.

Authenticatie

Ondersteunde mediatypen (kind)

1) Een media-adres ophalen

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 is voor afspelen of zelf kopiëren; nav_url draagt Content-Disposition: attachment en is geschikt om direct in de adresbalk van de browser te plakken om te downloaden (handig wanneer sommige mobiele browsers blob-downloads niet ondersteunen).

⚠️ Geldigheid van het adres: 7 dagen — kopieer het bestand op tijd

url / nav_url wijzen naar de objectopslag van het platform en vervallen standaard na 7 dagen (de bestanden worden teruggehaald en het oude adres geeft 404). Kopieer ze binnen die 7 dagen naar uw eigen opslag.

Na het vervallen hoeft het nummer niet opnieuw te worden gegenereerd: roep POST /api/music/download-url opnieuw aan (of geef refresh: true mee) voor nieuwe geldige adressen van dat nummer. Deze endpointgroep is gratis en kost niets extra.

2) Eén bestand rechtstreeks downloaden

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

De antwoordbody is een bestandsstream (geen JSON) en Content-Disposition bevat al de bestandsnaam. De songtekst en de songtekst met tijdstempels zijn alleen met dit endpoint op te halen (download-url geeft alleen media-adressen, geen songtekst). Het .lrc-bestand wordt momenteel alleen voor sommige nummers ondersteund; geeft het success:false terug, maak de .lrc dan zelf met de API voor songteksten met tijdstempels zoals in de volgende sectie, en probeer het niet opnieuw.

Songteksten met tijdstempels (.lrc) ophalen

Twee stappen worden aanbevolen, en ze werken voor elk nummer:

Stap 1: de woord-voor-woord-tijdlijn ophalen (gratis)

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

Het antwoord is direct een array (geen data-wrapper); elk element ziet er zo uit: {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word bevat al regeleindes, dus u kunt het per regel splitsen; voor de betekenis van de velden, het uitfilteren van instrumentale stukken en andere aandachtspunten zie "Velden" en "Gebruiksopmerkingen" van de API voor songteksten met tijdstempels.

Stap 2: de .lrc zelf opbouwen uit start_s (tijdnotatie [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 downloadt de door de server gemaakte .lrc ook direct, maar momenteel worden alleen sommige nummers ondersteund: geeft het success:false terug, maak het dan zelf zoals hierboven — opnieuw proberen is niet nodig en de facturering verandert niet.

3) Pakketdownload

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

Gebruik song_id (één) of song_ids (batch, tot 50 items). De antwoordbody is een ZIP-stream.

4) Stabiel downloadadres

GET /api/music/download?song_id=<id>&kind=<kind> is het downloadtoegangspunt dat direct in nummerantwoorden staat. Het accepteert zowel een API-sleutel als een browsersessie, gedraagt zich hetzelfde als download-file en is geschikt om vast in een client of externe speler te zetten.

5) Meeluisteren tijdens het genereren

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

Een playable_until_completed van true betekent dat dit een tijdelijk meeluisteradres is voor een nummer dat nog wordt gegenereerd; stap over op het definitieve adres zodra het nummer klaar is. Als één nummer mislukt, krijgt dat item een error-veld en komen de overige nummers gewoon terug.

Opmerkingen

• Alle endpoints geven alleen adressen terug van media die door het platform worden gehost; ze geven nooit Suno's versleutelde bron of een tijdelijk ondertekend adres terug.
• Adressen zijn niet permanent: kopieer de bestanden zelf als u ze lang wilt bewaren; gebruik download-file als u het originele bestand op schijf nodig hebt.
• Voor de MIDI van een stem moet de separatie van die stem afgerond zijn, anders volgt een foutmelding.