API di separazione (voce e base)

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

Descrizione dell'endpoint

La separazione divide un brano esistente in voce, base o risultati multitraccia. Il flusso di integrazione consigliato è:

1. Se l'audio di origine non è un brano generato su questa piattaforma, chiama prima l'API di caricamento dell'audio di origine.
2. Chiama POST /api/music/separate per inviare l'attività di separazione.
3. Interroga il risultato con l'API di consultazione e cronologia dei brani.
4. Usa gli endpoint di download per scaricare il file audio di ogni risultato di separazione.

Endpoint: POST /api/music/separate

Fatturazione: A pagamento. stem_mode=two attualmente 0,6 ¥ per chiamata per impostazione predefinita; stem_mode=twelve è una separazione multitraccia e attualmente 3,0 ¥ per chiamata per impostazione predefinita. L'importo effettivamente addebitato segue la configurazione prezzi del back-office.

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.

Autenticazione

Parametri della richiesta

Informazioni su stem_mode

Informazioni sulla separazione

La separazione è una capacità fissa e indipendente: non serve indicare né scegliere un modello di generazione dei brani. Il cliente invia solo il brano di origine e stem_mode; il server se ne occupa in base alla modalità.

Da dove vengono i numeri: un invio produce 2 versioni (due risultati dello stesso materiale), quindi il numero è 2 × le tracce di quella modalità: 4 per two e 24 per twelve. Basati sempre sulla lunghezza reale dell'array clips nella risposta; non scrivere cicli su un numero fisso (singole tracce possono fallire e quelle riuscite vengono restituite come al solito).

Quali tracce restituisce ogni modalità

Le 12 tracce della modalità twelve (i nomi sono fissati dalla piattaforma; l'ordine può variare):

La modalità two restituisce due tracce, (Vocals) e (Instrumental), ciascuna in 2 versioni. I titoli delle tracce di two e twelve sono nomi fissi (non contengono il nome del brano di origine), quindi non aspettarti di capire dal titolo da quale brano provengono.

I titoli delle tracce non valgono come chiave univoca. Nelle due versioni compaiono tracce con lo stesso nome (per esempio due (Vocals), due (Strings)), e una separazione restituisce molte tracce. Usa sempre song_id come identificatore e song_title solo per la visualizzazione; non usare nemmeno gli indici dell'array (l'ordine può cambiare).

Esempi di richiesta

Separazione voce / base (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

Separazione multitraccia (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

Risposta

In caso di successo viene di solito restituito un array di risultati di separazione. Ogni risultato è un clip di brano indipendente e va interrogato finché status non raggiunge uno stato completato.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

Sopra sono mostrate solo 2 delle 4 voci della modalità two; in pratica ne vengono restituite 4 (2 versioni × {(Vocals), (Instrumental)}); la modalità twelve ne restituisce 24. Il numero reale è la lunghezza dell'array clips.

Di solito il cliente deve solo salvare clips[].song_id; le consultazioni e i download successivi ruotano attorno a questi ID.

Note

• I risultati della separazione non compaiono nella cronologia di GET /api/music/songs (quell'elenco restituisce solo brani generati ordinari). Dopo un invio riuscito salva subito clips[].song_id, altrimenti dopo non riuscirai a trovarli.
• Ogni traccia è un'opera indipendente: ogni traccia ha il proprio song_id e va interrogata fino al completamento e scaricata separatamente.
• La fatturazione non dipende dal numero di voci: si paga per chiamata (two 0,6 ¥ per chiamata, twelve 3,0 ¥ per chiamata), e 4 o 24 voci costano lo stesso.
• Download: usa il song_id di quella traccia con POST /api/music/download-url / download-file (gratuito), oppure direttamente l'audio_url del risultato della consultazione; per il MIDI vedi l'API di recupero MIDI.
• Non inviare due volte: la separazione è un endpoint sincrono, quindi dopo un timeout verifica prima con la consultazione dei brani invece di ritentare subito (duplica l'ordine e riaddebita).
• Nascondi le tracce che non ti servono più con l'API di eliminazione delle tracce separate.

Consultare i risultati della separazione

Dopo un invio riuscito, consulta i risultati con clips[].song_id tramite POST /api/music/query.

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

Esempio di consultazione completata:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

Scaricare i file delle tracce

Quando un risultato di separazione è completo, puoi scaricare un singolo file di traccia con l'endpoint di download.

Endpoint: POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind supporta:

Per scaricare in pacchetto le risorse correlate di un risultato di separazione, chiama:

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

Descrizione degli stati

Errori frequenti

Note di compatibilità

La documentazione precedente usava esempi a oggetto singolo come success/task_id/vocals_url/instrumental_url. La separazione attuale si basa sull'array di brani clips[]: ogni risultato di separazione ha il proprio song_id, e le consultazioni e i download successivi ruotano attorno a questi song_id.

Pagine correlate

• Se vuoi solo separare voce e base senza scegliere una modalità, usa l'API di rimozione della voce; è la forma rapida a due tracce di questo endpoint ed è attualmente gratuita.
• Nascondi le tracce di separazione che non ti servono più con l'API di eliminazione delle tracce separate (eliminazione logica, senza addebito).
• Per il MIDI di una traccia vedi l'API di recupero MIDI; per audio, copertina e altri media l' API di download e anteprima dei media dei brani.