API Replace Section (sostituzione di una sezione)

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

Descrizione dell'endpoint

Replace Section rigenera sul posto un intervallo di tempo di un brano esistente. Serve a correggere una riga del testo o a sostituire un passaggio.

Endpoint: POST /api/music/replace-section

Fatturazione: A pagamento, attualmente 0,6 ¥ per chiamata per impostazione predefinita. 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.

Parametri della richiesta

Headers

Parametri del body

startSeconds e endSeconds sono in secondi e accettano decimali; startSeconds deve essere minore di endSeconds e l'intervallo deve stare dentro la durata del brano originale. requestedAt si usa solo quando serve trasmettere l'ora della richiesta, come timestamp Unix in secondi (non millisecondi); di norma può essere omesso.

Anche la sostituzione è un'attività asincrona. Il clip restituito può partire in pending, e un indirizzo audio vuoto in quel momento è normale; usa il song_id reale restituito per consultare il risultato finale.

Lunghezza della sezione: almeno 2 secondi (importante)

L'intervallo da sostituire non può essere più corto di 2 secondi. Misurato: intervalli di 1,0 / 1,2 / 1,5 secondi sono tutti falliti, mentre 2,0 secondi e oltre hanno funzionato.

Quando l'intervallo è troppo corto, la piattaforma non risponde con un «errore di parametro» ma con un messaggio facile da fraintendere:

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

Quella frase non è un problema di account o di piano — la sezione è troppo corta. Allunga l'intervallo oltre 2 secondi e invia di nuovo.

Esempio di richiesta

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "testo di contesto completo",
    "contextWindowLyrics": "testo di contesto della finestra",
    "infillLyrics": "testo della sostituzione",
    "style": "Mandopop, acoustic",
    "title": "Versione sostituita",
    "negativeTags": "noise"
  }'

Risposta

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "Versione sostituita",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

Campi compatibili

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags