API pemisahan track (vokal dan instrumen)

Diperbarui 2026-09-18 · tim Suno-API

Deskripsi endpoint

Pemisahan track memecah lagu yang sudah ada menjadi vokal, instrumen, atau hasil banyak track. Alur integrasi yang disarankan:

1. Bila audio sumber bukan lagu yang dibuat di platform ini, panggil dulu API unggah audio sumber.
2. Panggil POST /api/music/separate untuk mengirim tugas pemisahan.
3. Kueri hasilnya dengan API kueri lagu dan riwayat.
4. Unduh berkas audio setiap hasil pemisahan lewat endpoint unduhan.

Endpoint: POST /api/music/separate

Biaya: Berbayar. stem_mode=two saat ini default 0,6 ¥ per panggilan; stem_mode=twelve adalah pemisahan banyak track dan saat ini default 3,0 ¥ per panggilan. Jumlah yang benar-benar ditagih mengikuti konfigurasi harga di back-office.

Waktu tunggu dan timeout (penting): ini endpoint sinkron — pesanan baru diterima dan diteruskan ke pembuatan saat respons tiba. Dari pengukuran, sebagian besar permintaan merespons dalam 1-3 detik, sekitar 10% melewati 30 detik, dan terlama sekitar 230 detik. Setel timeout klien 300 detik atau lebih; tidak ada respons bukan berarti tidak ada yang dibuat, dan jangan mencoba ulang langsung setelah timeout (itu menduplikasi pesanan dan menagih dua kali). Jika koneksi terputus, periksa lagi nanti dengan GET /api/music/songs. Lihat "Waktu tunggu dan pengaturan timeout" di Ringkasan API baru.

Autentikasi

Parameter permintaan

Tentang stem_mode

Tentang pemisahan track

Pemisahan track adalah kemampuan tetap yang berdiri sendiri: tidak perlu mengisi atau memilih model pembuatan lagu. Pelanggan hanya mengirim lagu sumber dan stem_mode; server menanganinya sesuai mode.

Dari mana angka itu berasal: sekali kirim menghasilkan 2 versi (dua hasil dari materi yang sama), jadi jumlahnya = 2 × jumlah track mode tersebut: two adalah 4, twelve adalah 24. Selalu berpatokan pada panjang sebenarnya array clips di respons; jangan menulis loop dengan jumlah tetap (sebagian track bisa gagal dan yang berhasil tetap dikembalikan seperti biasa).

Track apa saja yang dikembalikan setiap mode

12 track mode twelve (namanya ditetapkan platform; urutannya bisa berubah):

Mode two mengembalikan dua track, (Vocals) dan (Instrumental), masing-masing 2 versi. Nama track pada two dan twelve adalah nama tetap (tanpa nama lagu sumber), jadi jangan berharap bisa tahu lagunya dari nama itu.

Nama track tidak bisa dipakai sebagai kunci unik. Pada dua versi akan muncul track dengan nama sama (misalnya dua (Vocals), dua (Strings)), dan satu pemisahan mengembalikan banyak track. Selalu gunakan song_id sebagai pengenal dan song_title hanya untuk tampilan; jangan gunakan indeks array juga (urutannya bisa berubah).

Contoh permintaan

Pemisahan vokal / instrumen (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"
  }'

Pemisahan banyak track (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"
  }'

Respons

Saat berhasil biasanya dikembalikan array hasil pemisahan. Setiap hasil adalah klip lagu yang berdiri sendiri dan harus terus dikueri sampai status menjadi keadaan selesai.

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

Di atas hanya ditampilkan 2 dari 4 item mode two; sebenarnya dikembalikan 4 (2 versi × {(Vocals), (Instrumental)}); mode twelve mengembalikan 24. Jumlah sebenarnya adalah panjang array clips.

Pelanggan biasanya hanya perlu menyimpan clips[].song_id; kueri dan unduhan berikutnya berputar di sekitar ID ini.

Catatan

• Hasil pemisahan tidak muncul di riwayat GET /api/music/songs (daftar itu hanya mengembalikan lagu hasil pembuatan biasa). Setelah pengiriman berhasil, segera simpan clips[].song_id, jika tidak, nanti tidak akan bisa ditemukan.
• Setiap track adalah karya tersendiri: setiap track punya song_id sendiri dan harus dikueri sendiri sampai selesai serta diunduh sendiri.
• Biaya tidak bergantung pada jumlah item: ditagih per panggilan (two 0,6 ¥ per panggilan, twelve 3,0 ¥ per panggilan), 4 atau 24 item harganya sama.
• Unduhan: gunakan song_id track tersebut dengan POST /api/music/download-url / download-file (gratis), atau langsung audio_url dari hasil kueri; untuk MIDI lihat API pengambilan MIDI.
• Jangan mengirim dua kali: pemisahan adalah endpoint sinkron, jadi setelah timeout periksa dulu lewat kueri lagu, jangan langsung ulangi (pesanan menjadi ganda dan ditagih dua kali).
• Sembunyikan track yang tidak lagi dibutuhkan dengan API hapus stem.

Mengueri hasil pemisahan

Setelah pengiriman berhasil, kueri hasilnya dengan clips[].song_id lewat 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"
  }'

Contoh kueri yang sudah selesai:

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

Mengunduh berkas track

Setelah hasil pemisahan selesai, Anda bisa mengunduh satu berkas track dengan endpoint unduhan.

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 yang didukung:

Untuk mengunduh sumber daya terkait dari satu hasil pemisahan dalam bentuk paket, panggil:

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

Penjelasan status

Kesalahan umum

Catatan kompatibilitas

Dokumentasi lama memakai contoh objek tunggal seperti success/task_id/vocals_url/instrumental_url. Pemisahan versi sekarang berpatokan pada array lagu clips[]: setiap hasil pemisahan punya song_id sendiri, dan kueri serta unduhan berikutnya berputar di sekitar song_id tersebut.

Endpoint terkait

• Jika hanya ingin memisahkan vokal dan instrumen tanpa memilih mode, gunakan API penghapusan vokal; itu bentuk cepat dua track dari endpoint ini dan saat ini gratis.
• Sembunyikan track pemisahan yang tidak lagi dibutuhkan dengan API hapus stem (hapus lunak, tanpa biaya).
• Untuk MIDI sebuah track lihat API pengambilan MIDI; untuk audio, sampul, dan media lain lihat API unduhan dan pratinjau media lagu.