Replace Section-API (Abschnitt ersetzen)

Aktualisiert am 2026-09-18 · Suno-API-Team

Beschreibung des Endpunkts

Replace Section generiert einen Zeitbereich eines bestehenden Songs an Ort und Stelle neu. Das passt, um eine Songtextzeile zu korrigieren oder eine Passage auszutauschen.

Endpunkt: POST /api/music/replace-section

Abrechnung: Kostenpflichtig, derzeit standardmäßig 0,6 ¥ pro Aufruf. Der tatsächlich berechnete Betrag folgt der aktuellen Preis-Konfiguration im Backoffice.

Max Mode / Variety: Dieser Endpunkt unterstützt die optionalen Parameter max_mode und variety (0-4). Mit aktiviertem max_mode wird dieser Aufruf zum doppelten Preis abgerechnet (0,6 → 1,2 ¥ pro Aufruf); variety kostet nichts extra. Bedeutung und Schreibweise stehen im Abschnitt „Erweiterte Parameter“ in der Übersicht der neuen API.

Wartezeiten und Timeouts (wichtig): Dies ist ein synchroner Endpunkt — die Bestellung wird erst angenommen und der Generierung übergeben, wenn die Antwort eintrifft. Gemessen antworten die meisten Anfragen in 1-3 Sekunden, etwa 10 % brauchen länger als 30 Sekunden und die längste liegt bei rund 230 Sekunden. Setzen Sie den Client-Timeout auf 300 Sekunden oder mehr; keine Antwort bedeutet nicht, dass nichts generiert wurde, und wiederholen Sie nicht direkt nach einem Timeout (das dupliziert die Bestellung und berechnet erneut). Wenn die Verbindung abbrach, prüfen Sie später mit GET /api/music/songs. Siehe „Wartezeiten und Timeout-Einstellungen“ in der Übersicht der neuen API.

Anfrageparameter

Headers

Body-Parameter

startSeconds und endSeconds sind in Sekunden und erlauben Dezimalwerte; startSeconds muss kleiner als endSeconds sein, und der Bereich muss innerhalb der Dauer des Originalsongs liegen. requestedAt wird nur verwendet, wenn Sie die Anfragezeit übermitteln müssen, als Unix-Zeitstempel in Sekunden (nicht Millisekunden); normalerweise kann es entfallen.

Der Ersatz ist ebenfalls eine asynchrone Aufgabe. Der zurückgegebene Clip kann mit pending beginnen, und eine leere Audio-Adresse ist dann normal; fragen Sie das Endergebnis mit der zurückgegebenen echten song_id ab.

Abschnittslänge: mindestens 2 Sekunden (wichtig)

Der zu ersetzende Bereich darf nicht kürzer als 2 Sekunden sein. Gemessen: Bereiche von 1,0 / 1,2 / 1,5 Sekunden scheiterten alle, 2,0 Sekunden und mehr funktionierten.

Ist der Bereich zu kurz, antwortet die Plattform nicht mit einem „Parameterfehler“, sondern mit einer leicht fehlzuinterpretierenden Meldung:

{"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"}}

Dieser Satz ist kein Konto- oder Tarifproblem — der Abschnitt ist zu kurz. Verlängern Sie den Bereich über 2 Sekunden und senden Sie erneut.

Beispielanfrage

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": "vollständiger Kontext-Songtext",
    "contextWindowLyrics": "Kontext-Songtext des Fensters",
    "infillLyrics": "Ersatz-Songtext",
    "style": "Mandopop, acoustic",
    "title": "Ersetzte Version",
    "negativeTags": "noise"
  }'

Antwort

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

Kompatible Felder

• 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