Parça ayırma (vokal ve eşlik) API'si

2026-09-18 tarihinde güncellendi · Suno-API ekibi

Uç nokta açıklaması

Parça ayırma, var olan bir şarkıyı vokal, eşlik veya çok kanallı sonuçlara böler. Önerilen entegrasyon akışı şöyledir:

1. Kaynak ses bu platformda üretilmiş bir şarkı değilse önce Kaynak ses yükleme API'sini çağırın.
2. Ayırma görevini göndermek için POST /api/music/separate çağırın.
3. Sonucu Şarkı sorgulama ve geçmiş API'si ile yoklayın.
4. Her ayırma sonucunun ses dosyasını indirme uç noktalarıyla indirin.

Uç nokta: POST /api/music/separate

Faturalama: Ücretli. stem_mode=two şu anda varsayılan olarak çağrı başına 0,6 ¥; stem_mode=twelve çok kanallı ayırmadır ve şu anda varsayılan olarak çağrı başına 3,0 ¥. Gerçekte tahsil edilen tutar arka ofis fiyat yapılandırmasına göre belirlenir.

Bekleme süreleri ve zaman aşımları (önemli): bu uç nokta senkrondur — sipariş ancak yanıt geldiğinde kabul edilir ve üretime verilir. Ölçümlere göre isteklerin çoğu 1-3 saniyede yanıtlanır, yaklaşık %10'u 30 saniyeyi aşar ve en uzunu yaklaşık 230 saniyedir. İstemci zaman aşımını 300 saniye veya üzerine ayarlayın; yanıt gelmemesi hiçbir şey üretilmediği anlamına gelmez ve zaman aşımından hemen sonra yeniden denemeyin (siparişi çoğaltır ve tekrar ücret alır). Bağlantı koptuysa daha sonra GET /api/music/songs ile kontrol edin. Yeni API genel bakışı sayfasındaki "Bekleme süreleri ve zaman aşımı ayarları" bölümüne bakın.

Kimlik doğrulama

İstek parametreleri

stem_mode hakkında

Ayırma hakkında

Parça ayırma bağımsız ve sabit bir yetenektir: şarkı üretim modeli doldurmanız veya seçmeniz gerekmez. Müşteri yalnızca kaynak şarkıyı ve stem_mode değerini gönderir; gerisini sunucu moda göre yapar.

Sayılar nereden geliyor: tek gönderim 2 sürüm üretir (aynı materyalin iki sonucu), dolayısıyla sayı = 2 × o modun kanal sayısı: two için 4, twelve için 24. Her zaman yanıttaki clips dizisinin gerçek uzunluğunu esas alın; sabit sayıyla döngü kurmayın (tek tek kanallar başarısız olabilir, başarılı olanlar normal döner).

Her mod hangi kanalları döndürür

twelve modunun 12 kanalı (adları platform sabit verir; sıra değişebilir):

two modu (Vocals) ve (Instrumental) olmak üzere iki kanalı, her biri 2 sürüm olarak döndürür. two ve twelve kanal başlıkları sabit adlardır (kaynak şarkı adını taşımazlar), bu yüzden başlıktan hangi şarkı olduğunu anlamayı beklemeyin.

Kanal başlıkları benzersiz anahtar olarak kullanılamaz. İki sürümde aynı adlı kanallar çıkar (örneğin iki (Vocals), iki (Strings)), ayrıca bir ayırma çok sayıda kanal döndürür. Kimlik olarak her zaman song_id kullanın, song_title yalnızca gösterim içindir; dizi indekslerini de kullanmayın (sıra değişebilir).

İstek örnekleri

Vokal / eşlik ayırma (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"
  }'

Çok kanallı ayırma (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"
  }'

Yanıt

Başarı durumunda genellikle bir ayırma sonucu dizisi döner. Her sonuç bağımsız bir şarkı clip'idir ve status tamamlanmış duruma gelene kadar sorgulanmaya devam etmelidir.

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

Yukarıda two modunun 4 kaydından yalnızca 2'si gösteriliyor; gerçekte 4 kayıt döner (2 sürüm × {(Vocals), (Instrumental)}); twelve modu 24 kayıt döndürür. Gerçek sayı clips dizisinin uzunluğudur.

Müşteri genellikle yalnızca clips[].song_id değerini kaydetmelidir; sonraki sorgulamalar ve indirmeler bu ID'ler etrafında döner.

Notlar

• Ayırma sonuçları GET /api/music/songs şarkı geçmişinde görünmez (o liste yalnızca normal üretilmiş şarkıları döndürür). Gönderim başarılı olduysa clips[].song_id değerini hemen kaydedin; aksi halde sonradan bulmanın yolu kalmaz.
• Her kanal bağımsız bir eserdir: her kanalın kendi song_id'si vardır ve ayrı ayrı tamamlanana kadar sorgulanmalı, ayrı ayrı indirilmelidir.
• Faturalama kayıt sayısından bağımsızdır: çağrı başına alınır (two çağrı başına 0,6 ¥, twelve çağrı başına 3,0 ¥); 4 kayıt da 24 kayıt da aynı fiyattır.
• İndirme: o kanalın song_id değeriyle POST /api/music/download-url / download-file (ücretsiz) kullanın veya sorgu sonucundaki audio_url değerini doğrudan kullanın; MIDI için MIDI alma API'sine bakın.
• İki kez göndermeyin: parça ayırma senkron bir uç noktadır, bu yüzden zaman aşımından sonra hemen yeniden denemek yerine önce şarkı sorgusuyla doğrulayın (sipariş çoğalır ve tekrar ücret alınır).
• Artık gerekmediği kanalları Stem silme API'si ile gizleyin.

Ayırma sonuçlarını sorgulama

Gönderim başarılı olduktan sonra clips[].song_id ile POST /api/music/query çağırarak sonuçları sorgulayın.

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

Tamamlanmış sorgu örneği:

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

Kanal dosyalarını indirme

Ayırma sonucu tamamlandığında indirme uç noktasıyla tek bir kanal dosyasını indirebilirsiniz.

Uç nokta: 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 şunları destekler:

Bir ayırma sonucunun ilgili kaynaklarını paket halinde indirmek için şunu çağırın:

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

Durum açıklamaları

Sık görülen hatalar

Uyumluluk notları

Eski dokümantasyon success/task_id/vocals_url/instrumental_url gibi tek nesneli örnekler kullanıyordu. Güncel parça ayırma clips[] şarkı dizisini esas alır: her ayırma sonucunun kendi song_id'si vardır ve sonraki sorgulamalar ile indirmeler bu song_id değerleri etrafında döner.

İlgili sayfalar

• Yalnızca vokali ve eşliği ayırmak isteyip mod seçmek istemiyorsanız Vokal kaldırma API'sini kullanın; bu uç noktanın hızlı iki kanallı biçimidir ve şu anda ücretsizdir.
• Artık gerekmeyen ayırma kanallarını Stem silme API'si ile gizleyin (yumuşak silme, ücret alınmaz).
• Kanalın MIDI'si için MIDI alma API'si; ses, kapak ve diğer medya için Şarkı medyası indirme ve önizleme API'si.