API di download e anteprima dei media dei brani

Aggiornato il 2026-09-18 · team Suno-API

Descrizione dell'endpoint

Questo gruppo di endpoint separa «ottenere un indirizzo del media» da «scaricare davvero il file»:

• Per ottenere un indirizzo riproducibile o scaricabile direttamente (per esempio da inserire nel tuo player o da copiare in uno storage a oggetti): usa POST /api/music/download-url, oppure il GET /api/music/download già presente nelle risposte.
• Per far salvare il file direttamente al browser: usa POST /api/music/download-file (file singolo) o POST /api/music/download-all (pacchetto).
• Se il brano è ancora in generazione e vuoi ascoltarlo prima: usa POST /api/music/generation-stream-url.

Fatturazione: Tutto gratuito. Download e anteprima leggono solo media già ospitati dalla piattaforma; non chiamano Suno e non vengono addebitati.

Modello consigliato: suno-v6. Puoi usare suno-v6, suno-v6-wild o suno-v6-mini.

Autenticazione

Tipi di media supportati (kind)

1) Ottenere un indirizzo del 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 per la riproduzione o per copiarla da solo; nav_url porta Content-Disposition: attachment e si presta a essere incollato direttamente nella barra degli indirizzi del browser per scaricare (utile quando alcuni browser mobili non supportano il download via blob).

⚠️ Validità dell'indirizzo: 7 giorni — copia il file in tempo

url / nav_url puntano allo storage a oggetti della piattaforma e scadono di default dopo 7 giorni (i file vengono recuperati e il vecchio indirizzo restituisce 404). Copiali nel tuo storage entro questi 7 giorni.

Dopo la scadenza non serve rigenerare il brano: richiama POST /api/music/download-url (o passa refresh: true) per ottenere nuovi indirizzi validi di quel brano. Questo gruppo di endpoint è gratuito e non aggiunge addebiti.

2) Scaricare direttamente un file singolo

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

Il corpo della risposta è uno stream di file (non JSON) e Content-Disposition contiene già il nome del file. Il testo e il testo con timestamp si ottengono solo con questo endpoint (download-url restituisce solo indirizzi dei media, non il testo). Il file .lrc al momento è supportato solo per alcuni brani; se restituisce success:false, genera il .lrc da solo con l'API di testi con timestamp come nella sezione successiva, senza ritentare.

Come ottenere testi con timestamp (.lrc)

Si consigliano due passaggi, validi per qualsiasi brano:

Passo 1: ottenere la timeline parola per parola (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"}'

La risposta è un array diretto (senza wrapper data); ogni elemento ha la forma {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word contiene già le interruzioni di riga, quindi puoi dividerlo per riga; per il significato dei campi, il filtro delle parti strumentali e altre avvertenze vedi «Campi» e «Note d'uso» dell'API di testi con timestamp.

Passo 2: costruire il .lrc da solo da start_s (formato orario [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 scarica direttamente anche il .lrc generato dal server, ma attualmente solo alcuni brani sono supportati: se restituisce success:false, generalo da solo come sopra — non serve ritentare e la fatturazione non ne risente.

3) Download in pacchetto

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

Usa song_id (uno solo) oppure song_ids (lotto, fino a 50 voci). Il corpo della risposta è uno stream ZIP.

4) Indirizzo di download stabile

GET /api/music/download?song_id=<id>&kind=<kind> è il punto di ingresso per il download fornito direttamente nelle risposte dei brani. Accetta sia una chiave API sia una sessione browser, si comporta come download-file ed è adatto a essere fissato in un client o in un player di terze parti.

5) Anteprima durante la generazione

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 pari a true indica un indirizzo di anteprima temporaneo per un brano in generazione; passa all'indirizzo definitivo quando il brano è completo. Se un brano fallisce, quella voce porta un campo error e gli altri brani vengono restituiti come al solito.

Note

• Tutti gli endpoint restituiscono solo indirizzi di media ospitati dalla piattaforma; non restituiscono mai la sorgente cifrata di Suno né un indirizzo firmato temporaneo.
• Gli indirizzi non sono permanenti: copia i file da solo se devi conservarli a lungo; usa download-file quando ti serve il file originale su disco.
• Il MIDI di uno stem richiede che la separazione di quello stem sia terminata, altrimenti viene restituito un errore.