API voor scheiding (zang en begeleiding)

Bijgewerkt op 2026-09-18 · Suno-API-team

Beschrijving van het endpoint

Scheiding splitst een bestaand nummer op in zang, begeleiding of meersporenresultaten. De aanbevolen integratieflow is:

1. Is de bronaudio geen nummer dat op dit platform is gegenereerd, roep dan eerst de API voor het uploaden van bronaudio aan.
2. Roep POST /api/music/separate aan om de scheidingstaak te versturen.
3. Vraag het resultaat op met de API voor nummeropvraging en geschiedenis.
4. Gebruik de download-endpoints om het audiobestand van elk scheidingsresultaat te downloaden.

Endpoint: POST /api/music/separate

Facturering: Betaald. stem_mode=two momenteel standaard 0,6 ¥ per aanroep; stem_mode=twelve is een meersporensplitsing en momenteel standaard 3,0 ¥ per aanroep. Het werkelijk gefactureerde bedrag volgt de prijsconfiguratie in de back-office.

Wachttijden en timeouts (belangrijk): dit is een synchroon endpoint — de opdracht wordt pas geaccepteerd en aan generatie overgedragen wanneer het antwoord binnenkomt. Gemeten: de meeste verzoeken antwoorden in 1-3 seconden, ongeveer 10% duurt langer dan 30 seconden en de langste is ongeveer 230 seconden. Zet de client-timeout op 300 seconden of meer; geen antwoord betekent niet dat er niets is gegenereerd, en probeer niet direct na een timeout opnieuw (dat dupliceert de opdracht en rekent opnieuw af). Als de verbinding wegviel, controleer later met GET /api/music/songs. Zie "Wachttijden en timeout-instellingen" in het Overzicht van de nieuwe API.

Authenticatie

Verzoekparameters

Over stem_mode

Over scheiding

Scheiding is een zelfstandige vaste mogelijkheid: er hoeft geen model voor nummergeneratie te worden ingevuld of gekozen. De klant stuurt alleen het bronnummer en stem_mode; de server handelt het af volgens de modus.

Waar de aantallen vandaan komen: één inzending levert 2 versies (twee resultaten van hetzelfde materiaal), dus het aantal is 2 × het aantal sporen van die modus: 4 voor two en 24 voor twelve. Baseer u altijd op de werkelijke lengte van de clips-array in het antwoord; schrijf geen lus over een vast aantal (losse sporen kunnen mislukken en de geslaagde komen gewoon terug).

Welke sporen elke modus teruggeeft

De 12 sporen van modus twelve (de namen worden door het platform vastgelegd; de volgorde kan variëren):

Modus two geeft twee sporen terug, (Vocals) en (Instrumental), elk in 2 versies. De spoornamen van two en twelve zijn vaste namen (zonder de naam van het bronnummer), dus verwacht niet aan de titel te zien om welk nummer het gaat.

Spoornamen zijn geen unieke sleutel. In de twee versies komen sporen met dezelfde naam voor (bijvoorbeeld twee (Vocals), twee (Strings)), en één scheiding geeft veel sporen terug. Gebruik altijd song_id als identificatie en song_title alleen voor weergave; gebruik ook geen array-indexen (de volgorde kan veranderen).

Voorbeeldverzoeken

Zang-/begeleidingsscheiding (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"
  }'

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

Antwoord

Bij succes wordt meestal een array met scheidingsresultaten teruggegeven. Elk resultaat is een zelfstandige nummerclip die moet blijven worden opgevraagd tot status een voltooide toestand bereikt.

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

Hierboven zijn slechts 2 van de 4 items van modus two te zien; in de praktijk komen er 4 terug (2 versies × {(Vocals), (Instrumental)}); modus twelve geeft er 24 terug. Het werkelijke aantal is de lengte van de clips-array.

De klant hoeft meestal alleen clips[].song_id te bewaren; latere opvragingen en downloads draaien om die ID's.

Opmerkingen

• Scheidingsresultaten verschijnen niet in de geschiedenis van GET /api/music/songs (die lijst geeft alleen gewone gegenereerde nummers terug). Bewaar na een geslaagde inzending direct clips[].song_id, anders zijn ze later niet meer te vinden.
• Elk spoor is een zelfstandig werk: elk spoor heeft zijn eigen song_id en moet apart tot voltooiing worden opgevraagd en apart worden gedownload.
• De facturering is onafhankelijk van het aantal items: er wordt per aanroep gefactureerd (two 0,6 ¥ per aanroep, twelve 3,0 ¥ per aanroep), en 4 of 24 items kosten hetzelfde.
• Download: gebruik de song_id van dat spoor met POST /api/music/download-url / download-file (gratis), of direct de audio_url uit het opvraagresultaat; voor MIDI zie de MIDI-ophaal-API.
• Verstuur niet twee keer: scheiding is een synchroon endpoint, dus controleer na een timeout eerst met de nummeropvraging in plaats van direct opnieuw te proberen (dat dupliceert de opdracht en rekent opnieuw af).
• Verberg sporen die u niet meer nodig hebt met de API voor het verwijderen van stems.

Scheidingsresultaten opvragen

Vraag na een geslaagde inzending de resultaten op met clips[].song_id via 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"
  }'

Voorbeeld van een voltooide opvraging:

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

Spoorbestanden downloaden

Zodra een scheidingsresultaat voltooid is, kunt u één spoorbestand downloaden met het download-endpoint.

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 ondersteunt:

Om de bijbehorende resources van één scheidingsresultaat als pakket te downloaden, roept u aan:

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

Statusbeschrijving

Veelvoorkomende fouten

Compatibiliteitsopmerkingen

De oudere documentatie gebruikte voorbeelden met één object zoals success/task_id/vocals_url/instrumental_url. De huidige scheiding werkt met de nummer-array clips[]: elk scheidingsresultaat heeft zijn eigen song_id, en latere opvragingen en downloads draaien om die song_id's.

Gerelateerde pagina's

• Wil je alleen zang en begeleiding scheiden zonder een modus te kiezen, gebruik dan de API voor het verwijderen van zang; dat is de snelle twee-sporenvorm van dit endpoint en is momenteel gratis.
• Verberg scheidingssporen die u niet meer nodig hebt met de API voor het verwijderen van stems (soft delete, geen kosten).
• Voor de MIDI van een spoor zie de MIDI-ophaal-API; voor audio, cover en andere media de API voor het downloaden en beluisteren van nummer-media.