API di aggiunta della voce

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

Descrizione dell'endpoint

L'aggiunta della voce genera, riscrive o completa la parte vocale su un brano esistente o su una base strumentale.

Endpoint: POST /api/music/add-vocal

Fatturazione: A pagamento, fatturato in base al modello richiesto; l'importo effettivamente addebitato segue la configurazione prezzi 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; variety non costa nulla in più. Cosa significano e come inviarli è nella sezione «Parametri avanzati» della Panoramica della nuova API.

Modello consigliato: suno-v6. Sono disponibili suno-v6, suno-v6-wild e suno-v6-mini.

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

Esempio di richiesta

curl -X POST https://www.suno-api.io/api/music/add-vocal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "source_clip_id": "source_song_id",
    "lyrics": "[Verse]\nLa notte cade oltre la finestra\n[Chorus]\nCamminiamo verso la luce",
    "style_tags": "warm male vocal, mandopop, intimate",
    "song_title": "Versione con voce potenziata",
    "instrumental": false,
    "wait_completion": false
  }'

Risposta

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "result_song_id",
        "song_title": "Versione con voce potenziata",
        "status": "pending"
      },
      {
        "song_id": "result_song_id_2",
        "song_title": "Versione con voce potenziata",
        "status": "pending"
      }
    ]
  }
}

Una chiamata restituisce 2 risultati (fatturati come 2 brani); l'esempio ne mostra 2. Fai riferimento alla lunghezza dell'array clips e non impostare un numero fisso di iterazioni. Salva clips[].song_id e interroga l'API di consultazione e cronologia dei brani fino a completed.

Note

• L'aggiunta della voce significa «generare o riscrivere la parte vocale sul brano di origine»; non è la stessa cosa della preferenza vocal_gender.
• Per usare una voce clonata usa l'【Consigliato】 API profilo vocale; l'API di clonazione vocale e generazione con voce indicata (catena precedente) non è consigliata per le nuove integrazioni.