API di caricamento dell'audio di origine

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

Descrizione dell'endpoint

Il caricamento dell'audio di origine trasforma un file audio locale o remoto in un clip di origine che le funzioni successive possono usare: cover, estensione, sostituzione di sezione, separazione e altre.

Endpoint: POST /api/music/upload-source

Fatturazione: Gratuito. Questo endpoint carica solo l'audio di origine; non avvia alcuna attività di generazione.

Uso consigliato: è il passo 1 del «cover in due passi». Carica prima l'audio con questo endpoint (è gratuito e puoi riprovare ogni volta che fallisce) e conserva il clip_id restituito; dopo aver confermato che il caricamento è riuscito (status in stato completato), chiama l'API di cover da un clip di origine per avviare il cover — il corpo di quella richiesta è di poche centinaia di byte, quindi non può essere troncato in transito perché l'audio è troppo grande. Rispetto all'API in un solo passaggio carica e fai il cover, questa separazione è più robusta quando l'audio è grande, la rete è instabile o lo stesso materiale va riutilizzato più volte (estensione / sostituzione / separazione).

Consigli per il caricamento di file grandi

Al termine del caricamento conferma sempre che lo status nella risposta sia già completato e conserva il clip_id prima di passare al passo 2; un caricamento fallito non viene addebitato e non crea alcuna attività di generazione, basta riprovare.

Verifica file_url prima del caricamento

È il nostro server a scaricare file_url, non il browser. Il fatto che un URL si apra nel browser non dimostra che i server di produzione possano raggiungerlo.

Per i file locali usa un caricamento multipart con il campo file. Non usare file_url con link ByteDance o URL firmati temporanei se non sono pubblici e ancora validi quando invii la richiesta.

Esegui questo comando da un server pubblico prima di inviare la richiesta:

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

La richiesta GET deve terminare con HTTP 200, restituire un MIME audio e contenere dati. Pagine di login, HTML e codici 401, 403, 404 o 410 non sono utilizzabili dal server.

file_url download failed: HTTP 404 di solito indica una firma scaduta, un file eliminato o parametri URL mancanti.

Il caricamento è gratuito. Se il download di file_url fallisce non vengono creati clip_id, task del brano o chiamate di generazione e non viene addebitato nulla; non serve alcun rimborso.

Parametri della richiesta

Headers

Per le richieste JSON:

Non impostare Content-Type manualmente nelle richieste multipart; lo genera il client.

Parametri del corpo

Esempio di richiesta JSON

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "upload_type": "file_upload"
  }'

Esempio di richiesta multipart

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.mp3" \
  -F "file_name=source.mp3" \
  -F "upload_type=file_upload" \
  -F "model=suno-v6"

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

Risposta

{
  "clip_id": "uploaded_clip_id",
  "status": "complete",
  "title": "source.mp3",
  "image_url": "https://...",
  "audio_url": "https://...",
  "display_tags": "pop, vocal",
  "inferred_description": "uploaded source audio",
  "clip_metadata": {}
}