Stem-Trennung (Gesang/Begleitung)-API

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

Beschreibung des Endpunkts

Die Stem-Trennung zerlegt einen vorhandenen Song in Gesang, Begleitung oder Mehrspur-Ergebnisse. Der empfohlene Integrationsablauf ist:

1. Ist das Quellaudio kein auf dieser Plattform erzeugter Song, rufen Sie zuerst die API zum Hochladen von Quellaudio auf.
2. Rufen Sie POST /api/music/separate auf, um die Trennung zu starten.
3. Fragen Sie das Ergebnis mit der API zum Abfragen von Songs und zum Verlauf ab.
4. Laden Sie mit den Download-Endpunkten die Audiodatei jedes Trennergebnisses herunter.

Endpunkt: POST /api/music/separate

Abrechnung: Kostenpflichtig. stem_mode=two derzeit standardmäßig 0,6 ¥ pro Aufruf; stem_mode=twelve ist ein Mehrspur-Split und derzeit standardmäßig 3,0 ¥ pro Aufruf. Der tatsächlich berechnete Betrag folgt der Preis-Konfiguration im Backoffice.

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.

Authentifizierung

Anfrageparameter

Zu stem_mode

Zur Stem-Trennung

Die Stem-Trennung ist eine eigenständige feste Funktion: Es ist kein Song-Generierungsmodell anzugeben oder auszuwählen. Der Kunde übermittelt nur den Quell-Song und stem_mode; der Server verarbeitet alles je nach Modus.

Woher die Zahlen kommen: Eine Übermittlung erzeugt 2 Versionen (zwei Ergebnisse desselben Materials), also ist die Anzahl 2 × die Spurenzahl dieses Modus: 4 bei two und 24 bei twelve. Richten Sie sich immer nach der tatsächlichen Länge des clips-Arrays in der Antwort; schreiben Sie keine Schleife über eine feste Anzahl (einzelne Spuren können fehlschlagen, die erfolgreichen kommen wie gewohnt zurück).

Welche Spuren jeder Modus zurückgibt

Die 12 Spuren des Modus twelve (die Namen gibt die Plattform fest vor; die Reihenfolge kann variieren):

Der Modus two gibt zwei Spuren zurück, (Vocals) und (Instrumental), jeweils in 2 Versionen. Die Spurtitel von two und twelve sind feste Namen (sie enthalten nicht den Namen des Quell-Songs), erwarten Sie also nicht, am Titel zu erkennen, um welchen Song es geht.

Spurtitel taugen nicht als eindeutiger Schlüssel. In den zwei Versionen kommen gleichnamige Spuren vor (zum Beispiel zwei (Vocals), zwei (Strings)), und eine Trennung gibt viele Spuren zurück. Verwenden Sie immer song_id als Kennung und song_title nur zur Anzeige; nutzen Sie auch keine Array-Indizes (die Reihenfolge kann sich ändern).

Beispielanfragen

Gesang-/Begleitungstrennung (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"
  }'

Mehrspur-Split (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"
  }'

Antwort

Bei Erfolg wird üblicherweise ein Array von Trennergebnissen zurückgegeben. Jedes Trennergebnis ist ein eigenständiger Song-Clip und muss weiter abgefragt werden, bis status einen abgeschlossenen Zustand erreicht.

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

Oben sind nur 2 der 4 Einträge des Modus two gezeigt; tatsächlich kommen 4 zurück (2 Versionen × {(Vocals), (Instrumental)}); der Modus twelve gibt 24 zurück. Die echte Anzahl ist die Länge des clips-Arrays.

Der Kunde muss in der Regel nur clips[].song_id speichern; spätere Abfragen und Downloads drehen sich um diese IDs.

Hinweise

• Trennergebnisse erscheinen nicht im Song-Verlauf von GET /api/music/songs (diese Liste gibt nur gewöhnliche generierte Songs zurück). Speichern Sie nach einer erfolgreichen Übermittlung sofort clips[].song_id, sonst können Sie sie später nicht mehr finden.
• Jede Spur ist ein eigenständiges Werk: jede Spur hat ihre eigene song_id und muss einzeln bis zum Abschluss abgefragt und einzeln heruntergeladen werden.
• Die Abrechnung hängt nicht von der Anzahl ab: sie erfolgt pro Aufruf (two 0,6 ¥ pro Aufruf, twelve 3,0 ¥ pro Aufruf), und 4 oder 24 Einträge kosten dasselbe.
• Download: verwenden Sie die song_id dieser Spur mit POST /api/music/download-url / download-file (kostenlos) oder direkt die audio_url aus dem Abfrageergebnis; für MIDI siehe die MIDI-Abruf-API.
• Nicht doppelt übermitteln: die Stem-Trennung ist ein synchroner Endpunkt; prüfen Sie nach einem Timeout zuerst mit der Song-Abfrage, statt direkt zu wiederholen (das dupliziert die Bestellung und berechnet erneut).
• Blenden Sie nicht mehr benötigte Spuren mit der API zum Löschen von Stems aus.

Trennergebnisse abfragen

Nach einer erfolgreichen Übermittlung fragen Sie die Ergebnisse mit clips[].song_id über POST /api/music/query ab.

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

Beispiel einer abgeschlossenen Abfrage:

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

Stem-Dateien herunterladen

Sobald ein Trennergebnis abgeschlossen ist, können Sie eine einzelne Stem-Datei mit dem Download-Endpunkt herunterladen.

Endpunkt: 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 unterstützt:

Um die zugehörigen Ressourcen eines Trennergebnisses als Paket zu laden, rufen Sie auf:

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

Statusbeschreibung

Häufige Fehler

Kompatibilitätshinweise

Die ältere Dokumentation verwendete Einzelobjekt-Beispiele wie success/task_id/vocals_url/instrumental_url. Die aktuelle Stem-Trennung arbeitet mit dem Song-Array clips[]: jedes Trennergebnis hat seine eigene song_id, und spätere Abfragen und Downloads drehen sich um diese song_id.

Verwandte Seiten

• Wenn Sie nur Gesang und Begleitung trennen wollen, ohne einen Modus zu wählen, nutzen Sie die API zur Stimmenentfernung; sie ist die schnelle Zwei-Spur-Form dieses Endpunkts und derzeit kostenlos.
• Blenden Sie nicht mehr benötigte Trennspuren mit der API zum Löschen von Stems aus (logisches Löschen, keine Berechnung).
• Für das MIDI eines Stems siehe die MIDI-Abruf-API; für Audio, Cover und andere Medien die API zum Herunterladen und Anhören von Song-Medien.