Panoramica della documentazione Suno API

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

Basta registrarsi con un'e-mail per creare una chiave API. Ogni generazione costa 0,6 ¥ e restituisce 2 brani, con download MP3/WAV, cover, Extend, separazione delle tracce e clonazione vocale. URL di base: https://www.suno-api.io.

Questa pagina descrive i modelli disponibili, tutti gli endpoint di generazione e modifica, la fatturazione e l'ordine di lettura consigliato. Se è la prima integrazione, legga dall'alto verso il basso; anche i percorsi di diagnosi per 401/403/429 sono qui.

Risposte rapide

Come ottengo una chiave API? Si registri con un'e-mail, apra la console, vada in gestione token e crei un token. Non servono numero di telefono né carta.

Quanto costa una chiamata? Una generazione costa 0,6 ¥ e restituisce 2 brani. Le richieste di stato, il WAV, i testi con timestamp e i suggerimenti di prompt sono gratuiti.

Quali modelli sono supportati? suno-v6 (predefinito), suno-v6-wild e suno-v6-mini. I modelli di generazione standard v5.5 e precedenti sono ritirati; i lavori esistenti non sono interessati.

Qual è l'URL di base? https://www.suno-api.io, con l'intestazione Authorization: Bearer YOUR_API_KEY.

Modelli attualmente disponibili

I modelli che il cliente può indicare nella generazione standard sono suno-v6, suno-v6-wild e suno-v6-mini. Se model viene omesso si usa suno-v6.

I modelli standard suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 e suno-v5-5 sono ritirati. Nelle attività storiche quei nomi possono ancora comparire, ma sono dati storici e non significano che il modello sia utilizzabile per nuove richieste. La separazione delle tracce fa eccezione: vedi API di separazione (voce/accompagnamento).

Autenticazione

Tutti gli endpoint pubblici con chiave API usano le stesse intestazioni:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL di base:

https://www.suno-api.io

Convenzioni generali sui parametri

• Un number nel corpo della richiesta deve essere un numero JSON, mai una percentuale in forma di stringa. Un'intensità del 50% si scrive 0.5, mai 50 o 50%.
• Un boolean deve essere true o false. Non invii true, false, 0 o 1 come sostituti.
• I campi contrassegnati come "no" possono essere omessi del tutto. In caso di dubbio su un parametro, lo ometta e lasci al servizio il comportamento predefinito; non invii stringa vuota, null o 0 al posto di "non inviato", perché 0 è un valore valido per alcuni campi numerici.
• I nomi dei campi distinguono l'ortografia. Ogni pagina elenca il campo consigliato e gli alias compatibili; li invii esattamente come nella tabella. Dove la documentazione dice che snake_case e camelCase sono entrambi accettati, non invii entrambi.
• Tutti i campi di durata che terminano con _s o Seconds sono in secondi e accettano decimali. I timestamp Unix sono descritti a parte, specificando se in secondi o millisecondi.
• Un ID che inizia con pending: è un segnaposto della piattaforma, non un ID reale del brano. Lo usi solo dove l'endpoint lo documenta esplicitamente; altrimenti attenda il song_id reale.

Limiti dei campi di testo

Superare un limite restituisce HTTP 400 direttamente: non viene generato nulla, nulla viene pre-addebitato e non viene creata alcuna attività. Il conteggio è per caratteri Unicode (un ideogramma vale 1) e anche gli spazi iniziali e finali contano.

Il message di errore indica il campo interessato e la lunghezza misurata: bastano quei due numeri per accorciare il testo.

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Si applica a: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Un'eccezione: il campo description di POST /api/music/sounds è limitato a 100 caratteri, perché il percorso degli effetti sonori usa il limite più corto della piattaforma.

Generazione asincrona e indirizzi audio

Gli endpoint di generazione musicale funzionano per impostazione predefinita in modo asincrono. Quando la prima risposta riporta status pari a pending, submitted o processing, un audio_url, video_url o cover_url vuoto è normale e non indica un fallimento. Salvi il song_id reale (o il client_request_id restituito) e interroghi l'endpoint corrispondente; legga e scarichi un indirizzo audio solo quando lo stato è completato.

⚠️ Gli indirizzi audio scadono dopo 7 giorni: trasferisca i file in tempo

audio_url, wav_url, video_url e gli indirizzi restituiti dagli endpoint di download provengono dallo storage a oggetti della piattaforma e scadono per impostazione predefinita dopo 7 giorni (i file vengono riciclati; un indirizzo vecchio restituisce 404 / non scarica).

• Entro quei 7 giorni, copi i file nel proprio storage (storage a oggetti, CDN o disco del server). Non tratti i nostri indirizzi come link permanenti.
• Un indirizzo scaduto non richiede di rigenerare il brano e non costa nulla in più: richiami l'API di interrogazione dei brani (o l'API di download dei media) per ottenere un nuovo indirizzo valido.

Tempi di attesa e impostazione dei timeout

Gli endpoint di generazione sono sincroni: l'ordine viene accettato e consegnato alla piattaforma solo quando arriva la risposta. Prima, il servizio deve pianificare un account e superare il controllo di sicurezza necessario, senza alcuna risposta intermedia: nessun altro endpoint vede l'ordine. L'unica prova affidabile che "qualcosa è stato generato" è quindi la risposta stessa, non ciò che si osserva durante l'attesa.

Tempi misurati (produzione, famiglia /api/music/create, 18–20 settembre 2026)

• Circa il 10% delle richieste supera i 30 secondi e circa l'1% impiega 1–2 minuti. Una richiesta lenta di solito significa che questa volta serviva prima un controllo di sicurezza.
• Campi, forma della risposta, codici di errore e fatturazione sono invariati: le integrazioni esistenti devono solo alzare il timeout del client, nessun'altra modifica al codice.

Requisiti di integrazione

1. Imposti il timeout del client a 300 secondi o più. I client con 30, 60 o 120 secondi si disconnettono durante l'attesa.
2. Nessuna risposta non significa che non sia stato generato nulla. Con un timeout o una connessione caduta, l'ordine può essere già accettato e in generazione.
3. Non ritenti subito dopo un timeout: un invio duplicato crea un secondo ordine e addebita di nuovo.
4. Se la connessione è caduta, elenchi i brani con GET /api/music/songs (dal più recente) poco dopo: gli ordini accettati compaiono normalmente. Reinvii solo dopo aver confermato che l'ordine manca davvero.
5. Per segnalare un problema, includa l'intestazione di risposta X-Oneapi-Request-Id, così la singola richiesta si individua subito.

Non vuole tenere una connessione lunga? Usi la modalità ricevuta di accettazione. POST /api/music/create e POST /api/music/create/custom accettano una ricevuta opzionale: aggiunga "accept_mode": "async" al corpo (o l'intestazione X-Accept-Mode: async) e l'endpoint restituisce subito 202 con un numero di ricevuta, mentre la generazione continua in background; segua l'avanzamento con GET /api/music/requests/{request_id}. Un client con poche decine di secondi di timeout non può più scambiare "nessuna risposta" per "nulla generato", né addebitare due volte per i tentativi. Vedi "Modalità ricevuta di accettazione" nell'API di generazione in modalità semplice.

Per riferimento: python requests usa timeout=300, urllib usa urlopen(..., timeout=300), Node usa req.setTimeout(300000), curl usa --max-time 300.

Elenco degli endpoint consigliati

Gli endpoint /api/voice/clone/* e /api/music/generate-with-voice appartengono alla catena iniziale di clonazione vocale e non sono consigliati per nuove integrazioni; usi invece l'【Consigliato】 API profilo vocale.

Parametri avanzati: Max Mode e Variety

Gli endpoint di generazione supportano questi due parametri opzionali (ometterli mantiene comportamento e prezzo precedenti):

Endpoint che li supportano: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Il doppio del prezzo in pratica: un endpoint da 0,6 ¥ per chiamata diventa 1,2 ¥ con max_mode; generare con una voce scelta costa 1,2 ¥ per chiamata e 2,4 ¥ con Max Mode; anche la cover vocale dell'【Consigliato】 API profilo vocale costa 1,2 ¥ per chiamata (2,4 ¥ con max_mode).
• variety vale solo per la famiglia suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); inviarlo con altri modelli restituisce 400.
• Effetti sonori, separazione tracce, concat, WAV e le azioni di editing Studio (ritaglio, rimozione sezione, dissolvenza, inversione, velocità e simili) non conoscono questi parametri: inviarli esplicitamente restituisce 400, così un parametro non viene mai ignorato in silenzio.
• variety è l'intero 0-4; style_weight e weirdness_constraint sono decimali da 0 a 1, quindi le scale sono diverse.

Campi di risposta comuni dei brani

Gli endpoint di generazione, cover, extend, separazione e interrogazione restituiscono in genere un array di brani con questi campi:

Quattro passi per l'integrazione (esempio minimo)

Con questi quattro passi ottiene il primo brano; l'elenco completo dei campi di ogni passo è nella pagina corrispondente dell'elenco degli endpoint consigliati.

# 1) Inviare una generazione: 0,6 ¥, restituisce 2 brani
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Italian pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Interrogare finché status non è completed (3-5 secondi è un buon intervallo)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "il song_id restituito al passo 1"}'

# 3) Ottenere un indirizzo media: gli endpoint di lettura sono gratuiti; song / wav / video / cover / midi
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": "lo stesso song_id", "kind": "song"}'

In caso di problemi: 401 / 402 / 403 / 429 nella guida agli errori; timeout e addebiti duplicati nella sezione "Tempi di attesa e impostazione dei timeout"; il dettaglio di ogni endpoint nell'elenco qui sotto.

Raccomandazioni

• Le nuove integrazioni dovrebbero usare suno-v6 ovunque.
• Negli endpoint con prezzo predefinito, l'importo effettivo segue la configurazione prezzi del back office e il modello richiesto.
• Gli endpoint di generazione restituiscono prima un'attività; recuperi l'audio finale con /api/music/query.
• wait_completion=true blocca fino al termine ed è adatto a test a basso volume; in produzione è preferibile interrogare in modo asincrono.
• Gli endpoint di generazione possono impiegare molto a rispondere: imposti il timeout del client a 300 secondi o più e ricordi che "nessuna risposta" non è "nulla generato".
• Caricamento, cover, sostituzione e WAV dipendono dagli account della piattaforma e dai permessi sul clip sorgente; in caso di errore legga prima message o error_message.

Informazioni su questa documentazione

Questa pagina è stata riorganizzata sulle capacità realmente esposte dalla Create UI; le nuove integrazioni dovrebbero leggerla per prima. La documentazione API precedente resta nella sezione "Documentazione API precedente (compatibile)" per chi vuole mantenere il metodo precedente.