API di consultazione e cronologia dei brani

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

Questa pagina copre tre endpoint di consultazione gratuiti:

Se hai usato la modalità ricevuta di accettazione (accept_mode=async) su un endpoint di generazione, quello che hai in mano è un numero di ricevuta, non un ID brano. Segui l'avanzamento con GET /api/music/requests/{request_id} e torna agli endpoint di questa pagina quando hai il song_id reale. Vedi «Modalità ricevuta di accettazione» nella API di generazione in modalità semplice.

Autenticazione e ambito dei dati

Tutti e tre gli endpoint si autenticano con la stessa chiave API:

Authorization: Bearer YOUR_API_KEY

La cronologia dei brani è isolata per il user_id a cui appartiene la chiave API. Più chiavi create sotto lo stesso account principale possono leggere la cronologia di quell'account, ma non quella di un altro utente né di un altro account di sottosito.

Gli endpoint di cronologia restituiscono solo brani realmente generati. Sono esclusi:

• i record segnaposto di generazione che iniziano con pending:;
• i caricamenti di audio sorgente e i record di caricamento potenziato;
• i sotto-risultati, come la separazione voce/accompagnamento e gli stem;
• i brani di altri utenti o di account di sottosito.

1. Consultare lo stato di generazione

Consulta lo stato attuale e il risultato finale di uno o più ID brano.

Endpoint: POST /api/music/query

Fatturazione: Gratis.

Headers

Parametri del body

Esempio di richiesta

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Esempio di risposta

[
  {
    "song_id": "clip_id_1",
    "song_title": "Titolo del brano",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Testo della canzone",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Note di compatibilità

La documentazione precedente può mostrare song_ids come array. Oggi si consiglia una stringa separata da virgole, che è come l'endpoint viene realmente chiamato.

song_ids deve contenere ID brano reali. Un ID segnaposto che inizia con pending: non è un song_id finale e non può essere usato qui; interrogando solo ID segnaposto può tornare un array vuoto [].

model, model_version o il model_name di piattaforma in una risposta possono conservare valori storici. Le nuove attività devono usare suno-v6, suno-v6-wild o suno-v6-mini; da suno-v2 a suno-v5-5 sono ritirati, e vedere quei nomi nella cronologia non significa che il modello accetti ancora invii.

Finché un'attività è pending, submitted o processing, audio_url, video_url e cover_url possono essere vuoti: è normale per un'attività non conclusa. Non dedurre un errore solo perché l'indirizzo è vuoto; usa status e interroga di nuovo quando lo stato è completo. Solo se lo stato è completo e gli indirizzi restano vuoti vale la pena contattare l'assistenza indicando il song_id.

⚠️ Gli indirizzi audio durano 7 giorni — trasferisci i file in tempo

Gli audio_url, video_url (e altri indirizzi media come il WAV) restituiti qui sono serviti dallo storage a oggetti della piattaforma e scadono per impostazione predefinita dopo 7 giorni: i file vengono riciclati e il vecchio indirizzo restituisce 404.

• Sposta i file nel tuo storage entro quei 7 giorni; non trattare l'indirizzo come un link di lunga durata.
• Un indirizzo scaduto non richiede di rigenerare il brano e non viene riaddebitato: richiama questo endpoint (POST /api/music/query) per ottenere un indirizzo nuovo e valido di quel brano.

2. Consultare la cronologia brani dell'account

Elenca i brani generati dall'account principale a cui appartiene la chiave API corrente. Utile per costruire una tua lista brani, un selettore o una pagina di cronologia.

Endpoint: GET /api/music/songs

Fatturazione: Gratis.

Parametri di query

I risultati sono ordinati per created_at e per ID record interno in ordine decrescente, così l'ordine di paginazione resta stabile.

Recuperare un invio andato in timeout: gli endpoint di generazione non danno risposta intermedia prima dell'accettazione. Se il client è andato in timeout o la connessione è caduta durante l'invio, quell'ordine potrebbe essere già accettato e in generazione. Dai un'occhiata a questo endpoint (più recenti per primi): i brani accettati compaiono normalmente nell'elenco. Reinvia solo dopo aver confermato che davvero non c'è, per non pagare due volte. Vedi «Tempi di attesa e impostazione del timeout» nella Panoramica della nuova API.

Esempio di richiesta

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "La città di notte",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Campi della risposta

L'endpoint di elenco non restituisce prompt, campi di fatturazione, informazioni sull'account o risposte grezze. Per prompt e parametri di generazione chiama l'endpoint di dettaglio del brano.

3. Consultare i parametri di generazione

Consulta il prompt, lo stile, il modello e il brano sorgente che la piattaforma ha conservato quando il brano è stato generato.

Endpoint: GET /api/music/songs/:song_id

Fatturazione: Gratis.

Si possono leggere solo i brani dell'account principale a cui appartiene la chiave API corrente. I brani di altri utenti o di account di sottosito sono trattati uniformemente come «brano non trovato».

Parametro di path

Esempio di richiesta

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio di risposta

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "La città di notte",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "strade di città dopo la pioggia, testo su un incontro ritrovato",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "La città di notte",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

I campi di parameters

Il campo prompt_view (visualizza prompt, aggiunto il 2026-09-28)

prompt_view è una struttura normalizzata dedicata a «visualizza prompt»: organizza i dati in sezioni fisse per tipo di generazione, così il client non deve più decidere quale campo mostrare. È un campo puramente aggiuntivo: i campi vecchi (parameters, parameter_retention) mantengono nome e significato, e i client che non analizzano il campo nuovo non sono per nulla toccati.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Modalità personalizzata",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Quattro del mattino#701f37", "title_base": "Quattro del mattino", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "elettronica guochao, sub bass profondo, synth retrò",
    "style_tags": "elettronica guochao, sub bass profondo, synth retrò",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Campi che possono comparire in extended: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, più il gruppo degli effetti sonori sound_type / sound_bpm / sound_key / sound_loop. I valori vuoti non vengono mai restituiti.

Tre regole di visualizzazione (seguile invece di dedurre):

1. Distingui da dove viene lo stile: con style_source=suno_derived mostralo come «stile (dedotto da Suno dalla tua descrizione)» e mai come «il tuo stile»;
2. I prompt interni non compaiono mai: i tipi cover con voce restituiscono solo i 【requisiti di stile】/【requisiti di cover】 digitati dall'utente; l'impalcatura fissa che componiamo per il modello non compare in alcun campo (i dati storici sono ripuliti allo stesso modo);
3. Non indovinare i parametri mancanti: se extended non lo contiene, allora non fu registrato — usa retention per spiegare il motivo.

Note sulla conservazione dei parametri

parameter_retention serve a separare «è stato passato esplicitamente un valore vuoto» da «il campo non è mai stato salvato storicamente»:

• core_parameters_available: se esiste il record principale dell'attività; normalmente true per un dettaglio valido;
• extended_parameters_available: se è stato trovato un record di attività musicale estesa correlato;
• sources: da quali tabelle dati proviene questa risposta;
• unavailable_fields: campi che non possono essere recuperati in modo affidabile dalla cronologia; restituiscono null dentro parameters.

I brani storici comuni di solito conservano prompt, stile, titolo attuale, modello, tipo di generazione e brano sorgente, ma non hanno salvato separatamente tutti i parametri avanzati. La piattaforma non indovina mai i valori mancanti dal generation_type.

Alcune attività musicali estese hanno conservato anche il prompt originale, lo stile, il titolo, il modello e in più custom_mode, negative_tags, vocal_gender, style_weight e weirdness_constraint. Anche quando il record esteso esiste, instrumental, lyrics_mode e wait_audio possono restare irrecuperabili.

I titoli possono essere rinominati in seguito dall'utente. Quando un'attività storica comune non ha conservato un titolo originale separato, parameters.title può essere il titolo attuale; quando esiste un record di attività estesa, prevale il titolo di generazione originale lì conservato.

Non trovato o senza permessi

Gli errori di business usano una busta di risposta uniforme. Quando il brano non esiste o non appartiene all'account corrente:

{
  "success": false,
  "message": "song not found"
}

Questo errore di business oggi viene restituito con HTTP 200, quindi giudica il risultato dal campo success. Una chiave API assente, non valida, scaduta o disabilitata restituisce HTTP 401.

Note di sicurezza

Gli endpoint di cronologia e dettaglio non restituiscono mai:

• chiavi API o ID token;
• campi di quota, fatturazione o rimborso;
• informazioni sull'account o risposte grezze;
• chiavi interne dello storage a oggetti;
• errori di amministratore o errori di risorse interne.