ट्रैक अलग करने वाला (वोकल और संगत) API

2026-09-18 को अद्यतन · Suno-API टीम

एंडपॉइंट विवरण

ट्रैक अलग करना किसी मौजूदा गाने को वोकल, संगत या मल्टी-ट्रैक नतीजों में बाँटता है। सुझाया गया इंटीग्रेशन क्रम:

1. अगर स्रोत ऑडियो इस प्लेटफ़ॉर्म पर बना गाना नहीं है, तो पहले स्रोत ऑडियो अपलोड API कॉल करें।
2. अलगाव कार्य भेजने के लिए POST /api/music/separate कॉल करें।
3. गाना क्वेरी और इतिहास API से नतीजा पूछें।
4. डाउनलोड एंडपॉइंट से हर अलगाव नतीजे की ऑडियो फ़ाइल डाउनलोड करें।

एंडपॉइंट: POST /api/music/separate

बिलिंग: सशुल्क। stem_mode=two अभी डिफ़ॉल्ट 0.6 युआन प्रति कॉल; stem_mode=twelve मल्टी-ट्रैक अलगाव है और अभी डिफ़ॉल्ट 3.0 युआन प्रति कॉल। असल में कटने वाली रकम बैक-ऑफ़िस मूल्य कॉन्फ़िगरेशन के अनुसार होती है।

प्रतीक्षा समय और टाइमआउट (ज़रूरी): यह सिंक्रोनस एंडपॉइंट है — ऑर्डर तभी स्वीकार होता है और जनरेशन को सौंपा जाता है जब जवाब आ जाता है। मापन के अनुसार ज़्यादातर अनुरोध 1-3 सेकंड में जवाब देते हैं, लगभग 10% 30 सेकंड से ज़्यादा लेते हैं और सबसे लंबा लगभग 230 सेकंड का होता है। क्लाइंट टाइमआउट 300 सेकंड या ज़्यादा रखें; जवाब न आना इसका मतलब नहीं कि कुछ बना नहीं, और टाइमआउट के तुरंत बाद दोबारा कोशिश न करें (इससे ऑर्डर दोहरा होता है और दोबारा शुल्क लगता है)। अगर कनेक्शन टूट गया हो, तो बाद में GET /api/music/songs से जाँचें। नए API का अवलोकन में "प्रतीक्षा समय और टाइमआउट सेटिंग" देखें।

प्रमाणीकरण

अनुरोध पैरामीटर

stem_mode के बारे में

अलगाव के बारे में

ट्रैक अलग करना एक स्वतंत्र निश्चित क्षमता है: गाना जनरेशन मॉडल भरना या चुनना ज़रूरी नहीं। ग्राहक केवल स्रोत गाना और stem_mode भेजता है; सर्वर मोड के अनुसार संभालता है।

संख्याएँ कहाँ से आती हैं: एक भेजने पर 2 संस्करण बनते हैं (एक ही सामग्री के दो नतीजे), इसलिए संख्या = 2 × उस मोड के ट्रैक: two के लिए 4 और twelve के लिए 24। हमेशा प्रतिक्रिया में clips ऐरे की असली लंबाई को आधार मानें; निश्चित संख्या पर लूप न लिखें (कुछ ट्रैक विफल हो सकते हैं और सफल ट्रैक सामान्य रूप से लौटते हैं)।

हर मोड कौन-से ट्रैक लौटाता है

twelve मोड के 12 ट्रैक (नाम प्लेटफ़ॉर्म तय करता है; क्रम बदल सकता है):

two मोड दो ट्रैक लौटाता है, (Vocals) और (Instrumental), हर एक के 2 संस्करण। two और twelve के ट्रैक शीर्षक निश्चित नाम हैं (स्रोत गाने का नाम नहीं होता), इसलिए शीर्षक से यह पता लगाने की उम्मीद न करें कि कौन-सा गाना है।

ट्रैक शीर्षक को यूनिक कुंजी नहीं बनाया जा सकता। दो संस्करणों में एक ही नाम के ट्रैक आते हैं (जैसे दो (Vocals), दो (Strings)), और एक अलगाव कई ट्रैक लौटाता है। हमेशा song_id को पहचानकर्ता बनाएँ और song_title सिर्फ़ दिखाने के लिए रखें; ऐरे इंडेक्स भी न इस्तेमाल करें (क्रम बदल सकता है)।

अनुरोध उदाहरण

वोकल / संगत अलगाव (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"
  }'

मल्टी-ट्रैक अलगाव (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"
  }'

प्रतिक्रिया

सफल होने पर आम तौर पर अलगाव नतीजों का ऐरे लौटता है। हर नतीजा एक स्वतंत्र गाना क्लिप है और status पूर्ण स्थिति में आने तक पूछताछ जारी रखनी होती है।

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

ऊपर two मोड के 4 में से सिर्फ़ 2 आइटम दिखाए गए हैं; असल में 4 लौटते हैं (2 संस्करण × {(Vocals), (Instrumental)}); twelve मोड 24 लौटाता है। असली संख्या clips ऐरे की लंबाई है।

ग्राहक को आम तौर पर सिर्फ़ clips[].song_id सहेजना होता है; आगे की क्वेरी और डाउनलोड इन्हीं ID के इर्द-गिर्द होते हैं।

नोट

• अलगाव नतीजे GET /api/music/songs के गाना इतिहास में नहीं आते (वह सूची केवल सामान्य बने गाने लौटाती है)। सफल भेजने के बाद तुरंत clips[].song_id सहेजें, वरना बाद में उन्हें ढूँढने का रास्ता नहीं रहेगा।
• हर ट्रैक एक स्वतंत्र कृति है: हर ट्रैक की अपनी song_id होती है; उसे अलग-अलग पूरा होने तक पूछना और अलग-अलग डाउनलोड करना होता है।
• बिलिंग आइटम की संख्या पर निर्भर नहीं: प्रति कॉल शुल्क (two 0.6 युआन प्रति कॉल, twelve 3.0 युआन प्रति कॉल), 4 हों या 24, कीमत एक ही है।
• डाउनलोड: उस ट्रैक की song_id के साथ POST /api/music/download-url / download-file (निःशुल्क) इस्तेमाल करें, या क्वेरी नतीजे का audio_url सीधे लें; MIDI के लिए MIDI प्राप्ति API देखें।
• दो बार न भेजें: अलगाव सिंक्रोनस एंडपॉइंट है, इसलिए टाइमआउट के बाद पहले गाना क्वेरी से जाँचें, तुरंत दोबारा न करें (इससे ऑर्डर दोहरा होता है और दोबारा शुल्क लगता है)।
• जिन ट्रैक की ज़रूरत नहीं रही उन्हें स्टेम हटाने वाला API से छिपाएँ।

अलगाव नतीजे पूछना

सफल भेजने के बाद clips[].song_id लेकर 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"
  }'

पूरी हुई क्वेरी का उदाहरण:

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

ट्रैक फ़ाइलें डाउनलोड करना

अलगाव नतीजा पूरा होने पर डाउनलोड एंडपॉइंट से एक ट्रैक फ़ाइल डाउनलोड कर सकते हैं।

एंडपॉइंट: 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 समर्थित मान:

किसी एक अलगाव नतीजे के संबंधित संसाधन पैकेज में डाउनलोड करने के लिए कॉल करें:

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

स्थिति विवरण

सामान्य त्रुटियाँ

संगतता नोट

पुराने दस्तावेज़ success/task_id/vocals_url/instrumental_url जैसे एकल-ऑब्जेक्ट उदाहरण इस्तेमाल करते थे। मौजूदा अलगाव clips[] गाना ऐरे पर आधारित है: हर अलगाव नतीजे की अपनी song_id होती है, और आगे की क्वेरी व डाउनलोड इन्हीं song_id के इर्द-गिर्द होते हैं।

संबंधित एंडपॉइंट

• अगर सिर्फ़ वोकल और संगत अलग करने हैं और मोड चुनने की ज़रूरत नहीं, तो वोकल रिमूवल API इस्तेमाल करें; यह इस एंडपॉइंट का तेज़ दो-ट्रैक रूप है और अभी निःशुल्क है।
• जिन अलगाव ट्रैक की ज़रूरत नहीं रही उन्हें स्टेम हटाने वाला API से छिपाएँ (सॉफ़्ट डिलीट, कोई शुल्क नहीं)।
• किसी ट्रैक का MIDI MIDI प्राप्ति API से, और ऑडियो, कवर व अन्य मीडिया गाने की मीडिया डाउनलोड और प्रीव्यू API से लें।