API rozdzielania (wokal i podkład)

Zaktualizowano 2026-09-18 · zespół Suno-API

Opis punktu końcowego

Rozdzielanie dzieli istniejący utwór na wokal, podkład lub wynik wielościeżkowy. Zalecany przebieg integracji:

1. Jeśli dźwięk źródłowy nie jest utworem wygenerowanym na tej platformie, najpierw wywołaj API przesyłania dźwięku źródłowego.
2. Wywołaj POST /api/music/separate, aby zgłosić zadanie rozdzielania.
3. Odpytuj wynik przez API zapytań o utwory i historii.
4. Pobierz plik dźwiękowy każdego wyniku rozdzielania punktami końcowymi pobierania.

Punkt końcowy: POST /api/music/separate

Rozliczenie: Płatne. stem_mode=two obecnie domyślnie 0,6 ¥ za wywołanie; stem_mode=twelve to podział wielościeżkowy i obecnie domyślnie 3,0 ¥ za wywołanie. Faktycznie pobierana kwota zależy od konfiguracji cen w panelu administracyjnym.

Czasy oczekiwania i limity czasu (ważne): to punkt końcowy synchroniczny — zamówienie zostaje przyjęte i przekazane do generowania dopiero, gdy przyjdzie odpowiedź. Z pomiarów: większość żądań odpowiada w 1-3 sekundy, około 10% przekracza 30 sekund, a najdłuższe trwa około 230 sekund. Ustaw limit czasu klienta na 300 sekund lub więcej; brak odpowiedzi nie oznacza, że nic nie zostało wygenerowane, a ponawianie od razu po limicie czasu duplikuje zamówienie i pobiera opłatę ponownie. Jeśli połączenie się zerwało, sprawdź później przez GET /api/music/songs. Zobacz „Czasy oczekiwania i ustawienia limitu czasu” w Przeglądzie nowego API.

Uwierzytelnianie

Parametry żądania

O stem_mode

O rozdzielaniu

Rozdzielanie to niezależna, stała funkcja: nie trzeba podawać ani wybierać modelu generowania utworów. Klient wysyła tylko utwór źródłowy i stem_mode; serwer zajmuje się resztą zgodnie z trybem.

Skąd biorą się liczby: jedno zgłoszenie tworzy 2 wersje (dwa wyniki z tego samego materiału), więc liczba = 2 × liczba ścieżek danego trybu: 4 dla two i 24 dla twelve. Zawsze kieruj się rzeczywistą długością tablicy clips w odpowiedzi; nie pisz pętli po stałej liczbie (pojedyncze ścieżki mogą się nie udać, a udane wracają normalnie).

Jakie ścieżki zwraca każdy tryb

12 ścieżek trybu twelve (nazwy nadaje platforma; kolejność może się zmieniać):

Tryb two zwraca dwie ścieżki, (Vocals) i (Instrumental), każda w 2 wersjach. Nazwy ścieżek w two i twelve to stałe nazwy (nie zawierają nazwy utworu źródłowego), więc nie licz na to, że z tytułu poznasz, z którego utworu pochodzi ścieżka.

Nazw ścieżek nie można używać jako klucza unikalnego. W dwóch wersjach występują ścieżki o tej samej nazwie (na przykład dwie (Vocals), dwie (Strings)), a jedno rozdzielanie zwraca wiele ścieżek. Zawsze używaj song_id jako identyfikatora, a song_title tylko do wyświetlania; nie używaj też indeksów tablicy (kolejność może się zmieniać).

Przykłady żądania

Rozdzielenie wokalu / podkładu (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"
  }'

Podział wielościeżkowy (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"
  }'

Odpowiedź

W przypadku powodzenia zwykle zwracana jest tablica wyników rozdzielania. Każdy wynik to niezależny klip utworu, który trzeba dalej odpytwać, aż status osiągnie stan zakończony.

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

Powyżej pokazano tylko 2 z 4 pozycji trybu two; w praktyce zwracane są 4 (2 wersje × {(Vocals), (Instrumental)}); tryb twelve zwraca 24. Rzeczywista liczba to długość tablicy clips.

Klient zwykle musi zapisać tylko clips[].song_id; kolejne odpytania i pobierania krążą wokół tych ID.

Uwagi

• Wyniki rozdzielania nie pojawiają się w historii GET /api/music/songs (ta lista zwraca tylko zwykłe wygenerowane utwory). Po udanym zgłoszeniu od razu zapisz clips[].song_id, inaczej później nie będzie jak ich znaleźć.
• Każda ścieżka to niezależne dzieło: każda ma własne song_id i trzeba ją osobno odpytwać do zakończenia oraz osobno pobierać.
• Rozliczenie nie zależy od liczby pozycji: płatne za wywołanie (two 0,6 ¥ za wywołanie, twelve 3,0 ¥ za wywołanie), a 4 czy 24 pozycje kosztują tyle samo.
• Pobieranie: użyj song_id tej ścieżki z POST /api/music/download-url / download-file (bezpłatnie) albo wprost audio_url z wyniku odpytania; o MIDI przeczytasz w API pobierania MIDI.
• Nie zgłaszaj dwa razy: rozdzielanie to punkt końcowy synchroniczny, więc po przekroczeniu limitu czasu najpierw sprawdź przez zapytanie o utwory, a nie ponawiaj od razu (to duplikuje zamówienie i pobiera opłatę ponownie).
• Niepotrzebne ścieżki ukryj przez API usuwania ścieżek rozdzielonych.

Odpytywanie wyników rozdzielania

Po udanym zgłoszeniu odpytaj wyniki za pomocą clips[].song_id przez 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"
  }'

Przykład zakończonego odpytania:

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

Pobieranie plików ścieżek

Gdy wynik rozdzielania jest gotowy, możesz pobrać pojedynczy plik ścieżki punktem końcowym pobierania.

Punkt końcowy: 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 obsługuje:

Aby pobrać powiązane zasoby jednego wyniku rozdzielania w paczce, wywołaj:

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

Opis statusów

Częste błędy

Uwagi o zgodności

Starsza dokumentacja używała przykładów z pojedynczym obiektem, takich jak success/task_id/vocals_url/instrumental_url. Obecne rozdzielanie opiera się na tablicy utworów clips[]: każdy wynik ma własne song_id, a kolejne odpytania i pobierania krążą wokół tych song_id.

Powiązane strony

• Jeśli chcesz tylko oddzielić wokal od podkładu bez wybierania trybu, użyj API usuwania wokalu; to szybka dwuścieżkowa forma tego punktu końcowego i obecnie jest bezpłatna.
• Niepotrzebne ścieżki rozdzielania ukryj przez API usuwania ścieżek rozdzielonych (usunięcie miękkie, bez opłat).
• MIDI ścieżki znajdziesz w API pobierania MIDI; dźwięk, okładkę i inne media w API pobierania i odsłuchu mediów utworów.