API pemisahan trek (vokal dan iringan)

Dikemas kini 2026-09-18 · pasukan Suno-API

Penerangan endpoint

Pemisahan trek membahagikan lagu sedia ada kepada vokal, iringan atau hasil berbilang trek. Aliran integrasi yang disyorkan:

1. Jika audio sumber bukan lagu yang dijana di platform ini, panggil API muat naik audio sumber dahulu.
2. Panggil POST /api/music/separate untuk menghantar tugasan pemisahan.
3. Pertanyaan hasilnya dengan API pertanyaan lagu dan sejarah.
4. Muat turun fail audio bagi setiap hasil pemisahan dengan endpoint muat turun.

Endpoint: POST /api/music/separate

Pengebilan: Berbayar. stem_mode=two kini lalai 0.6 ¥ setiap panggilan; stem_mode=twelve ialah pemisahan berbilang trek dan kini lalai 3.0 ¥ setiap panggilan. Jumlah yang benar-benar dicaj mengikut tetapan harga dalam back-office.

Masa menunggu dan timeout (penting): ini endpoint segerak — pesanan hanya diterima dan dihantar ke penjanaan apabila respons tiba. Berdasarkan ukuran, kebanyakan permintaan membalas dalam 1-3 saat, kira-kira 10% melebihi 30 saat dan paling lama sekitar 230 saat. Tetapkan timeout klien kepada 300 saat atau lebih; tiada respons tidak bermakna tiada apa-apa dijana, dan jangan cuba semula sejurus selepas timeout (ia menggandakan pesanan dan mencaj dua kali). Jika sambungan terputus, periksa kemudian dengan GET /api/music/songs. Lihat "Masa menunggu dan tetapan timeout" dalam Gambaran keseluruhan API baharu.

Pengesahan

Parameter permintaan

Perihal stem_mode

Perihal pemisahan

Pemisahan trek ialah keupayaan tetap yang tersendiri: tidak perlu mengisi atau memilih model penjanaan lagu. Pelanggan hanya menghantar lagu sumber dan stem_mode; pelayan akan mengendalikannya mengikut mod.

Dari mana angka itu datang: satu penghantaran menghasilkan 2 versi (dua hasil daripada bahan yang sama), jadi bilangannya = 2 × bilangan trek mod itu: two ialah 4, twelve ialah 24. Sentiasa berpandukan panjang sebenar tatasusunan clips dalam respons; jangan tulis gelung dengan bilangan tetap (sebahagian trek mungkin gagal dan yang berjaya tetap dipulangkan seperti biasa).

Trek apa yang dipulangkan setiap mod

12 trek mod twelve (namanya ditetapkan platform; susunannya boleh berubah):

Mod two memulangkan dua trek, (Vocals) dan (Instrumental), masing-masing 2 versi. Nama trek bagi two dan twelve ialah nama tetap (tiada nama lagu sumber), jadi jangan harap dapat tahu lagunya daripada nama itu.

Nama trek tidak boleh dijadikan kunci unik. Dalam dua versi akan muncul trek dengan nama sama (contohnya dua (Vocals), dua (Strings)), dan satu pemisahan memulangkan banyak trek. Sentiasa gunakan song_id sebagai pengecam dan song_title hanya untuk paparan; jangan gunakan indeks tatasusunan juga (susunannya boleh berubah).

Contoh permintaan

Pemisahan vokal / iringan (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 berbilang trek (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

Apabila berjaya biasanya dipulangkan tatasusunan hasil pemisahan. Setiap hasil ialah klip lagu tersendiri dan perlu terus dipertanyakan sehingga 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 ditunjukkan 2 daripada 4 item mod two; sebenarnya 4 dipulangkan (2 versi × {(Vocals), (Instrumental)}); mod twelve memulangkan 24. Bilangan sebenar ialah panjang tatasusunan clips.

Pelanggan biasanya hanya perlu menyimpan clips[].song_id; pertanyaan dan muat turun seterusnya berkisar pada ID ini.

Nota

• Hasil pemisahan tidak muncul dalam sejarah GET /api/music/songs (senarai itu hanya memulangkan lagu janaan biasa). Selepas penghantaran berjaya, simpan clips[].song_id dengan segera, jika tidak ia tidak akan dapat dicari kemudian.
• Setiap trek ialah karya tersendiri: setiap trek mempunyai song_id sendiri dan perlu dipertanyakan sendiri sehingga selesai serta dimuat turun sendiri.
• Pengebilan tidak bergantung pada bilangan item: dicaj setiap panggilan (two 0.6 ¥ setiap panggilan, twelve 3.0 ¥ setiap panggilan), 4 atau 24 item harganya sama.
• Muat turun: gunakan song_id trek itu dengan POST /api/music/download-url / download-file (percuma), atau terus audio_url daripada hasil pertanyaan; untuk MIDI lihat API pengambilan MIDI.
• Jangan hantar dua kali: pemisahan ialah endpoint segerak, jadi selepas timeout periksa dulu melalui pertanyaan lagu, jangan terus cuba semula (pesanan berganda dan dicaj dua kali).
• Sembunyikan trek yang tidak diperlukan lagi dengan API padam stem.

Mempertanyakan hasil pemisahan

Selepas penghantaran berjaya, pertanyakan hasilnya dengan clips[].song_id melalui 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 pertanyaan yang 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"
  }
]

Memuat turun fail trek

Apabila hasil pemisahan selesai, anda boleh memuat turun satu fail trek dengan endpoint muat turun.

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

Untuk memuat turun sumber berkaitan satu hasil pemisahan sebagai pakej, 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 lazim

Nota keserasian

Dokumentasi lama menggunakan contoh objek tunggal seperti success/task_id/vocals_url/instrumental_url. Pemisahan versi sekarang berasaskan tatasusunan lagu clips[]: setiap hasil pemisahan mempunyai song_id sendiri, dan pertanyaan serta muat turun seterusnya berkisar pada song_id tersebut.

Endpoint berkaitan

• Jika hanya mahu memisahkan vokal dan iringan tanpa memilih mod, gunakan API penyingkiran vokal; ia bentuk pantas dua trek bagi endpoint ini dan buat masa ini percuma.
• Sembunyikan trek pemisahan yang tidak diperlukan lagi dengan API padam stem (padam lembut, tanpa kos).
• Untuk MIDI sesuatu trek lihat API pengambilan MIDI; untuk audio, kulit album dan media lain lihat API muat turun dan pratonton media lagu.