API de separare (voce și acompaniament)

Actualizat pe 2026-09-18 · echipa Suno-API

Descrierea endpoint-ului

Separarea împarte o piesă existentă în voce, acompaniament sau rezultate multi-pistă. Fluxul de integrare recomandat este:

1. Dacă audio-ul sursă nu este o piesă generată pe această platformă, apelează mai întâi API-ul de încărcare a audio-ului sursă.
2. Apelează POST /api/music/separate pentru a trimite sarcina de separare.
3. Interoghează rezultatul cu API-ul de interogare a pieselor și de istoric.
4. Folosește endpoint-urile de descărcare pentru a descărca fișierul audio al fiecărui rezultat de separare.

Endpoint: POST /api/music/separate

Facturare: Cu plată. stem_mode=two momentan implicit 0,6 ¥ per apel; stem_mode=twelve este o separare multi-pistă și momentan implicit 3,0 ¥ per apel. Suma efectiv debitată urmează configurația de prețuri din back-office.

Timpii de așteptare și timeout-urile (important): este un endpoint sincron — comanda este acceptată și transmisă spre generare doar când sosește răspunsul. Din măsurători, majoritatea cererilor răspund în 1-3 secunde, circa 10% depășesc 30 de secunde, iar cea mai lungă este de aproximativ 230 de secunde. Setează timeout-ul clientului la 300 de secunde sau mai mult; lipsa unui răspuns nu înseamnă că nu s-a generat nimic, iar reîncercarea imediat după un timeout dublează comanda și debitează din nou. Dacă conexiunea s-a întrerupt, verifică mai târziu cu GET /api/music/songs. Vezi „Timpii de așteptare și setarea timeout-ului” în Prezentarea noului API.

Autentificare

Parametrii cererii

Despre stem_mode

Despre separare

Separarea este o capabilitate fixă independentă: nu trebuie completat sau ales un model de generare a pieselor. Clientul trimite doar piesa sursă și stem_mode; serverul se ocupă conform modului.

De unde provin numerele: o trimitere produce 2 versiuni (două rezultate din același material), deci numărul este 2 × pistele acelui mod: 4 pentru two și 24 pentru twelve. Folosește întotdeauna lungimea reală a tabloului clips din răspuns; nu scrie bucle pe un număr fix (piste individuale pot eșua, iar cele reușite se returnează normal).

Ce piste returnează fiecare mod

Cele 12 piste ale modului twelve (numele sunt fixate de platformă; ordinea poate varia):

Modul two returnează două piste, (Vocals) și (Instrumental), fiecare în 2 versiuni. Titlurile pistelor din two și twelve sunt nume fixe (nu conțin numele piesei sursă), așa că nu te aștepta să deduci din titlu din ce piesă provin.

Titlurile pistelor nu pot fi folosite ca cheie unică. În cele două versiuni apar piste cu același nume (de exemplu două (Vocals), două (Strings)), iar o separare returnează multe piste. Folosește întotdeauna song_id ca identificator și song_title doar pentru afișare; nu folosi nici indexurile tabloului (ordinea se poate schimba).

Exemple de cerere

Separare voce / acompaniament (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"
  }'

Separare multi-pistă (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"
  }'

Răspuns

În caz de succes se returnează de obicei un tablou de rezultate de separare. Fiecare rezultat este un clip de piesă independent și trebuie interogat în continuare până când status ajunge într-o stare finalizată.

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

Mai sus sunt afișate doar 2 din 4 intrări ale modului two; în practică se returnează 4 (2 versiuni × {(Vocals), (Instrumental)}); modul twelve returnează 24. Numărul real este lungimea tabloului clips.

Clientul trebuie de obicei să salveze doar clips[].song_id; interogările și descărcările ulterioare se învârt în jurul acestor ID-uri.

Note

• Rezultatele separării nu apar în istoricul GET /api/music/songs (acea listă returnează doar piese generate obișnuite). După o trimitere reușită, salvează imediat clips[].song_id, altfel nu le vei mai putea găsi.
• Fiecare pistă este o operă independentă: fiecare pistă are propriul song_id și trebuie interogată separat până la finalizare și descărcată separat.
• Facturarea nu depinde de numărul de intrări: se face per apel (two 0,6 ¥ per apel, twelve 3,0 ¥ per apel), iar 4 sau 24 de intrări costă la fel.
• Descărcare: folosește song_id-ul pistei cu POST /api/music/download-url / download-file (gratuit) sau direct audio_url din rezultatul interogării; pentru MIDI vezi API de obținere MIDI.
• Nu trimite de două ori: separarea este un endpoint sincron, așa că după un timeout verifică mai întâi cu interogarea pieselor în loc să reîncerci imediat (duplică comanda și debitează din nou).
• Ascunde pistele de care nu mai ai nevoie cu API de ștergere a stemurilor.

Interogarea rezultatelor separării

După o trimitere reușită, interoghează rezultatele cu clips[].song_id prin 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"
  }'

Exemplu de interogare finalizată:

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

Descărcarea fișierelor de piste

Când un rezultat de separare este gata, poți descărca un singur fișier de pistă cu endpoint-ul de descărcare.

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 acceptă:

Pentru a descărca în pachet resursele asociate unui rezultat de separare, apelează:

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

Descrierea stărilor

Erori frecvente

Note de compatibilitate

Documentația veche folosea exemple cu un singur obiect, precum success/task_id/vocals_url/instrumental_url. Separarea actuală se bazează pe tabloul de piese clips[]: fiecare rezultat are propriul song_id, iar interogările și descărcările ulterioare se învârt în jurul acestor song_id.

Pagini conexe

• Dacă vrei doar să separi vocea de acompaniament fără să alegi un mod, folosește API de eliminare a vocii; este forma rapidă pe două piste a acestui endpoint și momentan este gratuită.
• Ascunde pistele de separare de care nu mai ai nevoie cu API de ștergere a stemurilor (ștergere logică, fără costuri).
• Pentru MIDI-ul unei piste vezi API de obținere MIDI; pentru audio, copertă și alte media API de descărcare și ascultare a conținutului media al pieselor.