API di cover da un clip di origine

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

Descrizione dell'endpoint

Il cover da un clip di origine riutilizza un clip di origine già caricato, o già esistente, e ne genera una nuova versione cover.

Endpoint: POST /api/music/generate-from-source

Fatturazione: A pagamento, attualmente 0,6 ¥ per chiamata per impostazione predefinita. Caricare l'audio di origine in sé è gratuito; l'addebito avviene quando si genera un cover dal clip di origine. L'importo effettivamente addebitato segue la configurazione prezzi attuale del back-office.

Max Mode / Variety: questo endpoint supporta i parametri opzionali max_mode e variety (0-4). Con max_mode attivo, questa chiamata viene fatturata al doppio del prezzo (0,6 → 1,2 ¥ per chiamata); variety non costa nulla in più. Significato e modalità di invio sono nella sezione «Parametri avanzati» della Panoramica della nuova API.

Tempi di attesa e timeout (importante): è un endpoint sincrono — l'ordine viene accettato e passato alla generazione solo quando arriva la risposta. Dai dati misurati, la maggior parte delle richieste risponde in 1-3 secondi, circa il 10% supera i 30 secondi e la più lunga arriva a circa 230 secondi. Imposta il timeout del client a 300 secondi o più; nessuna risposta non significa che non sia stato generato nulla, e non ritentare subito dopo un timeout (duplica l'ordine e riaddebita). Se la connessione è caduta, verifica più tardi con GET /api/music/songs. Vedi «Tempi di attesa e impostazione del timeout» nella Panoramica della nuova API.

Uso consigliato: è il passo 2 del «cover in due passi». Nel passo 1 carica con l'API di caricamento dell'audio di origine (gratis) e conserva il clip_id; nel passo 2 chiama questo endpoint per avviare il cover. Così l'audio compare solo nel passo gratuito: se il caricamento va male basta riprovare e non viene addebitato nulla, mentre il corpo della richiesta del passo a pagamento è di poche centinaia di byte, quindi difficilmente fallirà perché il trasferimento si è interrotto. L'API di caricamento e cover in un solo passaggio mette l'audio intero nel corpo della richiesta, quindi appena l'audio supera circa 8 MB viene facilmente troncato in transito e restituisce unexpected end of JSON input (vedi «File di grandi dimensioni e richieste troncate» in quella pagina).

Inoltre lo stesso clip_id può essere riutilizzato per Extend, Replace Section, la separazione e altre azioni successive: non serve caricare di nuovo l'audio.

Parametri della richiesta

Headers

Parametri del body

weirdnessConstraint, styleWeight e audio_weight accettano un decimale di proporzione da 0.0 a 1.0, non un intero percentuale; per esempio 50% si scrive 0.5. 0 è un valore valido; solo omettere il campo significa "non specificato". audio_weight corrisponde al metadata.control_sliders.audio_weight di Suno e controlla quanto il risultato si appoggia all'audio di riferimento; può essere incluso solo quando la richiesta contiene un sourceClipId valido o un audio di riferimento, quindi non inviarlo in una generazione normale di solo testo. Con customMode=true, scrivi il testo nuovo in prompt e fornisci insieme style e title; con customMode=false, scrivi la descrizione creativa in prompt. instrumental e waitAudio devono usare i booleani JSON true/false.

Questo endpoint risponde per impostazione predefinita in modo asincrono. Finché lo status restituito è pending, un audio_url vuoto è normale; attendi il completamento prima di usare l'indirizzo audio. sourceClipId deve essere un ID reale di brano/clip di origine: non usare un task_id, un client_request_id o un ID segnaposto pending:.

Che tipo di ID è sourceClipId

sourceClipId è l'identificatore reale del clip Suno usato come origine di questo cover. L'oggetto brano lato cliente della piattaforma di solito chiama questo identificatore song_id, mentre i parametri della richiesta di cover mantengono il nome sourceClipId; qui i due indicano lo stesso ID reale di brano.

Se l'origine è un caricamento potenziato, interroga prima l'attività di caricamento potenziato e attendi che status diventi completed, poi inserisci il song_id reale restituito in sourceClipId. Si consiglia di inserire anche l'audio_url e il title di quel risultato in sourceAudioUrl e sourceTitle.

Non inserire il task_id, il client_request_id o un ID segnaposto pending:enhanced-upload:* del caricamento potenziato in sourceClipId.

Esempio di richiesta

curl -X POST https://www.suno-api.io/api/music/generate-from-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "sourceClipId": "uploaded_or_existing_clip_id",
    "sourceAudioUrl": "https://example.com/source.mp3",
    "sourceTitle": "Titolo dell'audio di origine",
    "prompt": "Testo nuovo o direzione creativa",
    "customMode": true,
    "style": "Mandopop, warm vocal",
    "title": "Titolo del cover",
    "negativeTags": "noise",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false
  }'

Risposta

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Titolo del cover",
        "status": "pending"
      }
    ],
    "source_update": {}
  }
}

Note

Questo endpoint cerca di risolvere a quale account appartiene il clip di origine. Se il clip di origine non può essere usato direttamente, il server può ricaricarlo in base alle informazioni dell'audio di origine e poi generare.