API di caricamento potenziato

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

Descrizione dell'endpoint

Il caricamento potenziato invia un file audio locale; il sistema esegue il potenziamento in background e produce un brano completo e riproducibile. La chiamata di invio restituisce subito le informazioni dell'attività e il client interroga l'endpoint di consultazione per il progresso.

Endpoint di invio: POST /api/music/enhanced-upload

Consultazione di un'attività: GET /api/music/enhanced-upload/:id

Annullamento di un'attività: POST /api/music/enhanced-upload/:id/cancel

Consultazione dell'elenco: GET /api/music/enhanced-upload

Fatturazione: 10 ¥ per chiamata, addebitati in anticipo al prezzo fisso di suno-enhanced-upload. Se l'attività fallisce, o viene annullata nella fase consentita, l'importo addebitato in anticipo viene rimborsato automaticamente. L'importo effettivamente addebitato segue la configurazione prezzi attuale del back-office.

Flusso di chiamata

1. Chiama POST /api/music/enhanced-upload per inviare il file audio.
2. Salva il task_id restituito.
3. Chiama GET /api/music/enhanced-upload/:id per consultare progresso e risultato.
4. Quando Suno ha terminato il rendering finale, il servizio usa l'account Suno associato a quell'attività per chiamare l'endpoint di download autorizzato di Studio e scrive l'MP3 nel servizio media CN2.
5. L'attività passa a completed solo quando l'asset CN2 è pronto; a quel punto leggi l'indirizzo audio CDN da audio_url nella risposta.

/api/forbidden è un indirizzo segnaposto che può comparire nei metadati di Suno Studio; non è una risorsa riproducibile né scaricabile. Non viene mai restituito al cliente e non è usato come prova di completamento. Se il rendering è terminato ma CN2 sta ancora preparando, l'endpoint continua a restituire processing e non restituisce audio_url; il client deve continuare a interrogare e non considerare l'indirizzo vuoto un errore.

Inviare un caricamento potenziato

Headers

Parametri del form

Esempio di richiesta

L'esempio seguente usa la stessa forma di chiamata della validazione in produzione, ma la chiave API è stata sostituita da un segnaposto.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

Risposta

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

Consultare un'attività

Esempio di richiesta

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

Esempio di risposta in elaborazione

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

Esempio di risposta completata

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

Annullare un'attività

Si può annullare solo finché sia l'attività sia il flusso del backend sono nella fase queued. Una volta che l'attività entra in leasing, running, processing o è già completata, non è più annullabile.

Esempio di richiesta

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

Risposta

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

Se l'attività ha già iniziato l'elaborazione, l'endpoint restituisce:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

Consultare l'elenco delle attività

L'endpoint di elenco restituisce solo le attività di caricamento potenziato dell'utente a cui appartiene la chiave API corrente; le attività di generazione ordinaria, cover ed extend non vengono mescolate.

Parametri di query

Esempio di richiesta

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

Risposta

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

Riferimento dei campi della risposta

Note

• Attualmente l'endpoint supporta solo l'upload di file multipart; file_url e file_base64 in JSON non sono supportati.
• Il file inviato può pesare al massimo 80 MB.
• L'endpoint di invio è asincrono: una risposta queued significa che l'attività è in coda, non che l'audio sia pronto.
• L'annullamento vale solo per le attività che non hanno ancora iniziato l'elaborazione; una volta avviata l'elaborazione il flusso dell'account della piattaforma non viene interrotto.
• Non esporre chiavi API reali nel codice del client.

Avviare un cover al termine del caricamento potenziato

Quando il caricamento potenziato è terminato, puoi usare il risultato come clip di origine e chiamare POST /api/music/generate-from-source per avviare un cover.

Attenzione: il cover è un endpoint sincrono — l'ordine viene accettato solo all'arrivo della risposta, e nei casi misurati può attendere fino a circa 230 secondi. Imposta il timeout del client a 300 secondi o più e non ritentare subito dopo un timeout. Vedi «Tempi di attesa e impostazione del timeout» nella Panoramica della nuova API.

Interroga prima GET /api/music/enhanced-upload/:id finché task.status non è completed. A quel punto:

• task.song_id è l'ID reale del brano ed è il sourceClipId richiesto dall'endpoint di cover;
• conviene passare task.audio_url come sourceAudioUrl, così il server può gestire il caso in cui il clip di origine e l'account di esecuzione non coincidono;
• task.task_id è solo l'ID dell'attività di caricamento potenziato e non può essere usato come sourceClipId;
• pending:enhanced-upload:* è un ID segnaposto della fase di elaborazione e non può essere usato per un cover.

Per avviare il cover usa la stessa chiave API del caricamento potenziato e componi la richiesta secondo la corrispondenza seguente:

Compila gli altri parametri (testo, stile, titolo, modello) secondo l'API di cover da un clip di origine. Quando l'endpoint di cover restituisce il nuovo clips[].song_id, usa POST /api/music/query per consultare lo stato di generazione e l'audio finale.