एक ही चरण में अपलोड और कवर API

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

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

एक ही चरण में अपलोड और कवर एक ऑडियो फ़ाइल या ऑडियो URL भेजता है और उस स्रोत ऑडियो से कवर का नया संस्करण बनाता है।

एंडपॉइंट: POST /api/music/upload-cover

बिलिंग: सशुल्क, अभी डिफ़ॉल्ट 0.6 युआन प्रति कॉल। यह एंडपॉइंट "अपलोड करके कवर" है, यह इमेज कवर अपलोड करने के बारे में नहीं है। असल में कटने वाली रकम मौजूदा बैक-ऑफ़िस मूल्य कॉन्फ़िगरेशन के अनुसार होती है।

Max Mode / Variety: यह एंडपॉइंट वैकल्पिक पैरामीटर max_mode और variety (0-4) समर्थित करता है। max_mode चालू होने पर यह कॉल 2× दर पर बिल होती है (0.6 → 1.2 युआन प्रति कॉल); variety का कोई अतिरिक्त शुल्क नहीं है। दोनों का अर्थ और भेजने का तरीका नए API का अवलोकन के "उन्नत पैरामीटर" भाग में है।

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

ऑडियो बड़ा हो तो "अपलोड" और "कवर" को दो चरणों में बाँटना बेहतर है (सुझाया गया)

इस एंडपॉइंट के लिए पूरा ऑडियो अनुरोध बॉडी में डालना ज़रूरी है: ऑडियो जितना बड़ा, बॉडी उतनी बड़ी, और एक नेटवर्क झटका या टाइमआउट ट्रांसफ़र को बीच में काट देता है, जिसके बाद सर्वर unexpected end of JSON input लौटाता है (HTTP 400, कोई शुल्क नहीं)।

जब ऑडियो लगभग 8 MB से बड़ा हो, नेटवर्क अस्थिर हो या वही स्रोत सामग्री दोबारा इस्तेमाल होनी हो, तो दो-चरणीय रूप अपनाएँ:

1. POST /api/music/upload-source पहले स्रोत ऑडियो अपलोड करता है — निःशुल्क, कभी भी दोबारा कोशिश — और clip_id देता है;
2. POST /api/music/generate-from-source उस clip_id से कवर शुरू करता है — शुल्क वाले चरण की अनुरोध बॉडी केवल लगभग 250 बाइट होती है।

देखें स्रोत ऑडियो अपलोड API, स्रोत क्लिप से कवर API और इस पेज के अंत में "बड़ी फ़ाइलें और कटे अनुरोध"।

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

Headers

Body पैरामीटर

cover_start_s और cover_end_s सेकंड में हैं और दशमलव भी ले सकते हैं; आरंभ समय अंत समय से छोटा होना चाहिए और स्रोत ऑडियो की अवधि से अधिक नहीं हो सकता। दोनों फ़ील्ड छोड़ दें तो पूरा ऑडियो इस्तेमाल होता है। audio_weight Suno के metadata.control_sliders.audio_weight पर मैप होता है और तय करता है कि नतीजा संदर्भ ऑडियो पर कितना टिकता है; इसकी वैल्यू 0.0-1.0 होती है और इसे केवल तब शामिल किया जा सकता है जब अनुरोध में file_url या file_base64 के रूप में मान्य संदर्भ ऑडियो हो। 0 मान्य मान है; फ़ील्ड छोड़ने का अर्थ "निर्दिष्ट नहीं" है और Suno का डिफ़ॉल्ट व्यवहार बना रहता है। instrumental और waitAudio JSON बूलियन होने चाहिए, स्ट्रिंग नहीं।

अपलोड एंडपॉइंट डिफ़ॉल्ट रूप से असिंक्रोनस जवाब देता है। जब तक प्रतिक्रिया में clips[].status pending है, audio_url का खाली होना सामान्य है और इसका मतलब यह नहीं कि अपलोड या कवर विफल रहा; लौटाई गई असली song_id सहेजें और ऑडियो पता पढ़ने से पहले गाना क्वेरी एंडपॉइंट से पूरा होने तक पूछताछ करें।

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

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "नए बोल या रूपांतरण की दिशा",
    "style": "Mandopop, acoustic guitar",
    "title": "कवर संस्करण",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

प्रतिक्रिया

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "कवर संस्करण",
        "status": "pending"
      }
    ]
  }
}

बड़ी फ़ाइलें और कटे अनुरोध

सुझाव: अपलोड और कवर को दो चरणों में बाँटें

एक-बार वाला एंडपॉइंट (यही) अपलोड और जनरेशन को एक ही चरण में जोड़ता है: बड़ी बॉडी उसी एक चरण में होती है, इसलिए टूटने पर न पता चलता है कि कुछ बना या नहीं, और न यह कि शुल्क लगा या नहीं।

निष्कर्ष: ऑडियो लगभग 8 MB से ऊपर, नेटवर्क अस्थिर, या वही सामग्री कई बार → दो-चरणीय रूप; बहुत छोटा ऑडियो और स्थिर नेटवर्क → यह एंडपॉइंट अधिक आसान है।

400 unexpected end of JSON input का मतलब क्या है

इसका मतलब है कि सर्वर को मिला JSON अधूरा है (यह गलत पैरामीटर नहीं, न अनुमति या बैलेंस की समस्या है)। सामान्य कारण, संभावना के क्रम में:

1. बड़ी बॉडी ट्रांसफ़र के बीच कट गई: प्रवेश परत दोनों दर्ज करती है — "क्लाइंट ने कितने बाइट भेजने की घोषणा की" और "वास्तव में कितने पहुँचे"। मापा गया उदाहरण: क्लाइंट ने 14.17 MB घोषित किया पर पहुँचे केवल 11.8–12.4 MB, और तीनों अनुरोध लगभग 1.6–1.7 सेकंड पर रुक गए; कम पड़े बाइट की संख्या हर बार अलग थी, जो ट्रांसफ़र टूटने की ओर इशारा करती है, किसी तय सीमा की ओर नहीं (सर्वर अनुरोध बॉडी का आकार सीमित नहीं करता)।
2. Content-Length और वास्तव में भेजे गए बाइट का मेल न होना: Node.js में स्ट्रिंग के .length (UTF-16 अक्षरों की संख्या) को लंबाई मानने पर, सामग्री में चीनी या अन्य मल्टी-बाइट टेक्स्ट होते ही गणना गलत हो जाती है।
3. बॉडी को Buffer के बजाय स्ट्रिंग के रूप में लिखना, जिससे लिखे गए बाइट घोषित संख्या से मेल नहीं खाते।

तीनों स्थितियाँ शुल्क लगने से पहले होती हैं, इसलिए कोई खर्च नहीं बनता।

क्लाइंट-साइड स्वयं जाँच सूची

• Content-Length Buffer.byteLength(json, 'utf8') (या Buffer.from(json).length) से लें — json.length कभी नहीं;
• अनुरोध बॉडी Buffer के रूप में लिखें, स्ट्रिंग के रूप में नहीं;
• सॉकेट / अनुरोध टाइमआउट ≥ 300 सेकंड;
• ऑडियो लगभग 8 MB से बड़ा हो तो: file_url इस्तेमाल करें (बॉडी केवल कुछ सौ बाइट), या upload-source का multipart अपलोड, या सीधे दो-चरणीय रूप;
• multipart अनुरोधों में Content-Type हाथ से न सेट करें (boundary क्लाइंट जोड़ेगा);
• "वास्तव में भेजे गए बाइट" प्रिंट करें और Content-Length से तुलना करें;
• दो-चरणीय रूप में, चरण 2 भेजने से पहले पुष्टि करें कि चरण 1 ने clip_id और status पूर्ण अवस्था में लौटाए।

आम गलतियाँ

संबंधित एंडपॉइंट: स्रोत ऑडियो अपलोड API (चरण 1), स्रोत क्लिप से कवर API (चरण 2).