API di download Free2

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

Descrizione dell'endpoint

Free2 è un canale di download a pagamento separato: risolve file MP3/WAV/testo/metadati da un ID brano (o da un link brano di suno.com) e restituisce indirizzi di download ospitati dalla piattaforma. Accetta solo una chiave API — non accetta una sessione del browser — e la risposta non contiene mai la sorgente di riproduzione cifrata di Suno.

Endpoint: POST /api/music/free2

Fatturazione: addebitata per brano risolto con successo, attualmente 0,2 CNY per brano per impostazione predefinita. Scegliere più tipi di file in una richiesta non costa nulla in più; i brani che non si risolvono non vengono addebitati. Al massimo 10 brani per richiesta (dopo la deduplicazione); l'importo effettivamente addebitato segue la configurazione prezzi del back-office.

Modello consigliato: suno-v6. Sono disponibili suno-v6, suno-v6-wild e suno-v6-mini.

Autenticazione

Parametri della richiesta

Indica almeno uno tra song_id e song_ids; indica almeno un elemento in files.

Esempio di richiesta

curl -X POST https://www.suno-api.io/api/music/free2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["song_id_1", "song_id_2"],
    "files": ["mp3", "wav", "lyrics"]
  }'

Risposta

{
  "code": 200,
  "message": "success",
  "data": {
    "songs": [
      {
        "song_id": "song_id_1",
        "files": [
          {"type": "mp3", "url": "https://media.suno-api.io/assets/song_id_1-free2-v1-mp3.mp3"}
        ]
      },
      {
        "song_id": "song_id_2",
        "files": [],
        "error": {"code": "song_not_found", "message": "song not found or not owned by the current user"}
      }
    ],
    "requested_songs": 2,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

Se viene richiesto un solo brano, la risposta restituisce anche song_id e files al livello superiore, per compatibilità con la vecchia forma a brano singolo.

Riusare gli indirizzi in cache (gratuito)

Per un brano già scaricato, un nuovo download non richiede una nuova risoluzione e non viene addebitato di nuovo: usa POST /api/music/free2/cached per ottenere gli indirizzi attuali dei file che questo account aveva scaricato in precedenza.

Endpoint: POST /api/music/free2/cached

Fatturazione: Gratuito. È una cache di sola lettura: nessuna risoluzione, nessuna transcodifica, nessun addebito; restituisce solo indirizzi già pronti e non recuperati.

⚠️ Validità dell'indirizzo di download: 7 giorni — salvalo per tempo. songs[].files[].url è fornito dall'object storage della piattaforma e scade per impostazione predefinita dopo 7 giorni (i file vengono recuperati e il vecchio indirizzo restituisce 404); salvali nel tuo storage entro quei 7 giorni. Dopo la scadenza, richiama POST /api/music/free2 per prepararli di nuovo e ottenere un indirizzo valido (quella ri-preparazione viene addebitata secondo le regole normali; /api/music/free2/cached restituisce solo indirizzi di cache ancora validi).

Parametri della richiesta: identici a POST /api/music/free2 (uno tra song_id / song_ids / songs, e almeno un elemento in files).

curl -X POST https://www.suno-api.io/api/music/free2/cached \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "song_ids": ["98ca3f1d-…", "a185b3d9-…"], "files": ["mp3"] }'

{
  "success": true,
  "data": {
    "items": [
      { "song_id": "98ca3f1d-…", "type": "mp3", "url": "https://…/assets/98ca3f1d-…-free2-v1-mp3.mp3" }
    ],
    "songs": [
      { "song_id": "98ca3f1d-…", "files": [ { "type": "mp3", "url": "https://…" } ], "missing_files": [] },
      { "song_id": "a185b3d9-…", "files": [], "missing_files": ["mp3"] }
    ],
    "missing": ["a185b3d9-…"]
  }
}

Gli indirizzi vengono restituiti solo per i brani che hai già scaricato; i brani senza storico di download, o i cui asset sono già stati recuperati, compaiono solo in missing e non restituiscono alcun indirizzo.

Note

• POST /api/music/free2 può risolvere qualunque brano pubblico su Suno (compresi brani non presenti su questa piattaforma); quando un brano non si risolve, viene restituito un error solo per quel brano e gli altri dello stesso lotto non sono interessati. Al contrario, POST /api/music/free2/cached restituisce indirizzi solo per i brani scaricati da questo account.
• La prima risoluzione di un brano crea i file ospitati, che poi vengono riusati; non passare tipi duplicati in files, il server deduplica automaticamente.
• Differenza rispetto all'API di download e anteprima dei media dei brani: Free2 è a pagamento, accetta direttamente i link suno.com e non offre, oltre al testo, tipi come timeline/MIDI.