Suno API दस्तावेज़ — अवलोकन

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

ईमेल पते से पंजीकरण करें और आप API कुंजी बना सकते हैं। एक जनरेशन की कीमत 0.6 युआन है, उससे 2 गाने मिलते हैं, और उसमें MP3/WAV डाउनलोड, कवर गाने, Extend, स्टेम और आवाज़ क्लोनिंग शामिल हैं। बेस URL: https://www.suno-api.io।

इस पेज पर मौजूदा उपलब्ध मॉडल, हर जनरेशन और एडिटिंग एंडपॉइंट, बिलिंग का तरीका और पढ़ने का सुझाया गया क्रम दिया गया है। यदि आप पहली बार इंटीग्रेशन कर रहे हैं तो इसे ऊपर से नीचे पढ़ें; 401/403/429 की समस्या-निवारण प्रविष्टियाँ भी यहीं हैं।

छोटे जवाब

API कुंजी कैसे मिलेगी? ईमेल पते से पंजीकरण करें, कंसोल खोलें, टोकन प्रबंधन में जाएँ और एक टोकन बनाएँ। न फ़ोन नंबर चाहिए और न बैंक कार्ड।

एक कॉल की कीमत क्या है? एक जनरेशन की कीमत 0.6 युआन है और उससे 2 गाने मिलते हैं। स्टेटस क्वेरी, WAV, टाइमस्टैम्प वाले बोल और प्रॉम्प्ट सुझाव मुफ़्त हैं।

कौन-से मॉडल समर्थित हैं? suno-v6 (डिफ़ॉल्ट), suno-v6-wild और suno-v6-mini। v5.5 और उससे पुराने मानक जनरेशन मॉडल हटा दिए गए हैं; मौजूदा काम पर इसका असर नहीं होता।

बेस URL क्या है? https://www.suno-api.io, साथ में हेडर Authorization: Bearer YOUR_API_KEY।

मौजूदा उपलब्ध मॉडल

मानक गाना बनाने के लिए ग्राहकों को उपलब्ध मॉडल हैं suno-v6, suno-v6-wild और suno-v6-mini। जब model न दिया जाए तो suno-v6 इस्तेमाल होता है।

मानक मॉडल suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 और suno-v5-5 हटा दिए गए हैं। पुराने टास्क में ये नाम अब भी दिख सकते हैं; वह ऐतिहासिक डेटा है, यह संकेत नहीं कि वह मॉडल नए अनुरोधों के लिए इस्तेमाल हो सकता है। स्टेम इसका अपवाद है — देखें स्टेम (गायन/संगीत अलगाव) API।

प्रमाणीकरण

API कुंजी वाला हर सार्वजनिक एंडपॉइंट एक ही हेडर सेट इस्तेमाल करता है:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

बेस URL:

https://www.suno-api.io

सामान्य पैरामीटर नियम

• रिक्वेस्ट बॉडी में number को JSON संख्या होना चाहिए, प्रतिशत वाली स्ट्रिंग नहीं। 50% तीव्रता 0.5 लिखी जाती है, कभी 50 या 50% नहीं।
• boolean को true या false होना चाहिए। इसके बदले 0 या 1 न भेजें।
• जिन फ़ील्ड पर "नहीं" लिखा है, उन्हें पूरी तरह छोड़ा जा सकता है। जब पक्का न हो कि कोई पैरामीटर क्या करता है, तो उसे छोड़ दें ताकि सेवा अपना डिफ़ॉल्ट व्यवहार इस्तेमाल करे; "न भेजे गए" के बदले खाली स्ट्रिंग, null या 0 न भेजें, क्योंकि 0 कुछ संख्यात्मक फ़ील्ड के लिए वैध मान है।
• फ़ील्ड नाम की वर्तनी महत्वपूर्ण है। हर एंडपॉइंट पेज सुझाया गया नाम और संगत वैकल्पिक नाम बताता है; पैरामीटर तालिका के अनुसार ही भेजें। जहाँ दस्तावेज़ कहते हैं कि snake_case और camelCase दोनों स्वीकार्य हैं, वहाँ दोनों एक साथ न भेजें।
• _s या Seconds पर खत्म होने वाला हर अवधि फ़ील्ड सेकंड में है और दशमलव स्वीकार करता है। Unix टाइमस्टैम्प अलग से समझाए गए हैं, जिसमें यह भी कि वे सेकंड में हैं या मिलीसेकंड में।
• pending: से शुरू होने वाला ID प्लेटफ़ॉर्म का प्लेसहोल्डर है, असली song_id नहीं। उसे केवल वहीं इस्तेमाल करें जहाँ एंडपॉइंट प्लेसहोल्डर समर्थन साफ़ तौर पर लिखता हो; बाकी जगह असली song_id का इंतज़ार करें।

टेक्स्ट फ़ील्ड की सीमाएँ

टेक्स्ट सीमा पार करने पर सीधे HTTP 400 मिलता है: कुछ बनता नहीं, कोई पहले से शुल्क नहीं कटता और कोई टास्क रिकॉर्ड नहीं बनता। गिनती यूनिकोड अक्षरों में होती है (एक चीनी अक्षर 1 गिना जाता है) और आरंभ/अंत की स्पेस भी गिनी जाती हैं।

message फ़ील्ड बताता है कि कौन-सा फ़ील्ड सीमा पार कर रहा है और मापी गई लंबाई क्या है, इसलिए छोटा करने के लिए ये दो संख्याएँ ही काफ़ी हैं:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

लागू होता है: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

एक अपवाद: POST /api/music/sounds का description फ़ील्ड 100 अक्षर तक सीमित है, क्योंकि साउंड-इफ़ेक्ट पथ प्लेटफ़ॉर्म की छोटी सीमा इस्तेमाल करता है।

असिंक्रोनस जनरेशन और ऑडियो पते

म्यूज़िक जनरेशन एंडपॉइंट डिफ़ॉल्ट रूप से असिंक्रोनस काम करते हैं। जब पहली प्रतिक्रिया में status का मान pending, submitted या processing हो, तो audio_url, video_url या cover_url का खाली होना सामान्य है और इसका मतलब टास्क विफल होना नहीं। असली song_id (या एंडपॉइंट से मिला client_request_id) सहेजें और मेल खाते क्वेरी एंडपॉइंट को कॉल करें; ऑडियो पता तभी पढ़ें और डाउनलोड करें जब स्टेटस पूरा हो चुका हो।

⚠️ ऑडियो पते 7 दिन बाद समाप्त हो जाते हैं — अपनी फ़ाइलें समय रहते स्थानांतरित करें

audio_url, wav_url, video_url और डाउनलोड एंडपॉइंट से मिलने वाले पते प्लेटफ़ॉर्म के ऑब्जेक्ट स्टोरेज से परोसे जाते हैं और डिफ़ॉल्ट रूप से 7 दिन बाद समाप्त हो जाते हैं (फ़ाइलें रीसाइकल हो जाती हैं; पुराना पता 404 देता है / डाउनलोड नहीं होता)।

• उन 7 दिनों के भीतर फ़ाइलों को अपने स्टोरेज में ले जाएँ (अपना ऑब्जेक्ट स्टोरेज, CDN या सर्वर डिस्क)। हमारे पतों को दीर्घकालिक लिंक न मानें।
• समाप्त पते के लिए गाना दोबारा बनाने की ज़रूरत नहीं और कोई अतिरिक्त खर्च नहीं: उसी गाने का नया वैध पता लेने के लिए गाना क्वेरी API (या मीडिया डाउनलोड API) फिर से कॉल करें।

प्रतीक्षा समय और टाइमआउट सेटिंग

जनरेशन एंडपॉइंट सिंक्रोनस हैं: ऑर्डर तभी स्वीकार होता है और बनाने के लिए प्लेटफ़ॉर्म को सौंपा जाता है जब प्रतिक्रिया आ जाती है। उससे पहले सेवा को एक खाता शेड्यूल करना और ज़रूरी सुरक्षा जाँच पार करनी होती है, और बीच में कोई प्रतिक्रिया नहीं होती — कोई दूसरा एंडपॉइंट भी वह ऑर्डर नहीं देख सकता। इसलिए "कुछ बना है" का एकमात्र भरोसेमंद प्रमाण प्रतिक्रिया ही है, प्रतीक्षा के दौरान दिखने वाली कोई भी चीज़ नहीं।

मापे गए प्रतीक्षा समय (प्रोडक्शन में /api/music/create परिवार, 2026-09-18 से 2026-09-20)

• लगभग 10% अनुरोध 30 सेकंड से ज़्यादा लेते हैं और लगभग 1% 1–2 मिनट लेते हैं। धीमा अनुरोध आम तौर पर इसका मतलब है कि उस बार पहले सुरक्षा जाँच पार करनी पड़ी।
• अनुरोध फ़ील्ड, प्रतिक्रिया का स्वरूप, त्रुटि कोड और बिलिंग नहीं बदले हैं, इसलिए मौजूदा इंटीग्रेशन को केवल क्लाइंट टाइमआउट बढ़ाना है — और कोई कोड बदलाव नहीं।

इंटीग्रेशन की शर्तें

1. क्लाइंट टाइमआउट 300 सेकंड या ज़्यादा रखें। जो क्लाइंट 30, 60 या 120 सेकंड पर चलते हैं वे इंतज़ार के दौरान कनेक्शन काट देंगे।
2. प्रतिक्रिया न आना इसका मतलब नहीं कि कुछ बना नहीं। टाइमआउट या कनेक्शन टूटने पर ऑर्डर पहले ही स्वीकार हो चुका हो सकता है और बन रहा हो सकता है।
3. टाइमआउट के तुरंत बाद दोबारा कोशिश न करें: दोहरी सबमिशन दूसरा ऑर्डर बनाती है और फिर से शुल्क कटता है।
4. यदि कनेक्शन टूट गया हो, तो थोड़ी देर बाद GET /api/music/songs (सबसे नए पहले) से अपने गाने सूचीबद्ध करें — स्वीकार किए गए ऑर्डर सामान्य रूप से दिखते हैं। दोबारा तभी भेजें जब पक्का हो जाए कि ऑर्डर वाकई नहीं है।
5. समस्या बताते समय प्रतिक्रिया हेडर X-Oneapi-Request-Id साथ भेजें ताकि उसी अनुरोध का सीधे पता लगाया जा सके।

लंबा कनेक्शन नहीं रखना चाहते? रसीद-स्वीकृति मोड इस्तेमाल करें। POST /api/music/create और POST /api/music/create/custom एक वैकल्पिक स्वीकृति रसीद समर्थित करते हैं: बॉडी में "accept_mode": "async" जोड़ें (या हेडर X-Accept-Mode: async) और एंडपॉइंट तुरंत 202 के साथ रसीद संख्या लौटाता है, जबकि जनरेशन पृष्ठभूमि में चलता रहता है; प्रगति के लिए GET /api/music/requests/{request_id} कॉल करें। जिन क्लाइंट का टाइमआउट केवल कुछ दसियों सेकंड है, वे "कोई प्रतिक्रिया नहीं" को गलती से "कुछ बना नहीं" नहीं पढ़ेंगे, और दोबारा कोशिश से दोहरा शुल्क भी नहीं लगेगा। देखें सरल मोड जनरेशन API में "रसीद-स्वीकृति मोड"।

संदर्भ के लिए: python requests में timeout=300, urllib में urlopen(..., timeout=300), Node में req.setTimeout(300000), curl में --max-time 300।

सुझाए गए एंडपॉइंट की सूची

/api/voice/clone/* और /api/music/generate-with-voice पहली पीढ़ी की आवाज़-क्लोनिंग श्रृंखला हैं और नए इंटीग्रेशन के लिए सुझाई नहीं जातीं; इसके बजाय 【सुझाया गया】 वॉइस प्रोफ़ाइल API इस्तेमाल करें।

उन्नत पैरामीटर: Max Mode और Variety

जनरेशन एंडपॉइंट इन दो वैकल्पिक पैरामीटरों को समर्थित करते हैं (न देने पर पहले वाला व्यवहार और कीमत बनी रहती है):

ये दोनों पैरामीटर इनमें समर्थित हैं: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• व्यवहार में 2× कीमत: जो एंडपॉइंट 0.6 युआन प्रति कॉल है वह max_mode के साथ 1.2 युआन हो जाता है; चुनी हुई आवाज़ से बनाना 1.2 युआन प्रति कॉल है और Max Mode के साथ 2.4 युआन; 【सुझाया गया】 वॉइस प्रोफ़ाइल API का आवाज़-कवर भी 1.2 युआन प्रति कॉल है (max_mode के साथ 2.4 युआन)।
• variety केवल suno-v6 परिवार (suno-v6, suno-v6-wild, suno-v6-mini) पर लागू होता है; किसी और मॉडल के साथ भेजने पर 400 मिलता है।
• साउंड इफ़ेक्ट, स्टेम, concat, WAV और Studio की एडिटिंग क्रियाएँ (crop, हिस्सा हटाना, fade, उलटा करना, गति बदलना इत्यादि) ये पैरामीटर नहीं लेतीं — साफ़ तौर पर भेजने पर 400 मिलता है, ताकि कोई पैरामीटर चुपचाप नज़रअंदाज़ न हो।
• variety कच्चा पूर्णांक 0-4 है; जबकि style_weight और weirdness_constraint 0 से 1 तक दशमलव हैं, यानी पैमाने अलग हैं।

गाने की आम प्रतिक्रिया फ़ील्ड

जनरेशन, कवर, extend, अलगाव और क्वेरी एंडपॉइंट आम तौर पर इन फ़ील्डों वाले गानों की सरणी लौटाते हैं:

इंटीग्रेशन के चार चरण (न्यूनतम काम करने वाला उदाहरण)

ये चार चरण पूरे कर लें और आपका पहला गाना तैयार है; हर चरण की पूरी फ़ील्ड सूची सुझाए गए एंडपॉइंट की सूची में मौजूद उसी पेज पर है।

# 1) जनरेशन अनुरोध भेजें: 0.6 युआन, 2 गाने मिलते हैं
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) जब तक status completed न हो, टास्क को पोल करें (हर 3-5 सेकंड ठीक अंतराल है)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "चरण 1 में मिला song_id"}'

# 3) मीडिया पता लें: पढ़ने वाले एंडपॉइंट सब मुफ़्त हैं; song / wav / video / cover / midi उपलब्ध हैं
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "वही song_id", "kind": "song"}'

कुछ गड़बड़ होने पर: 401 / 402 / 403 / 429 के बारे में त्रुटि संदर्भ में है; टाइमआउट और दोहरा शुल्क ऊपर "प्रतीक्षा समय और टाइमआउट सेटिंग" में; और हर एंडपॉइंट का ब्यौरा नीचे सुझाए गए एंडपॉइंट की सूची में।

सिफ़ारिशें

• नए इंटीग्रेशन पूरे फ़्लो में suno-v6 इस्तेमाल करें।
• जो एंडपॉइंट डिफ़ॉल्ट कीमत बताते हैं, उनमें असल कटौती मौजूदा बैक-ऑफ़िस मूल्य कॉन्फ़िगरेशन और माँगे गए मॉडल के अनुसार होती है।
• जनरेशन एंडपॉइंट आम तौर पर पहले टास्क लौटाते हैं; अंतिम ऑडियो /api/music/query से पढ़ें।
• wait_completion=true पूरा होने तक रोकता है और कम मात्रा के परीक्षण के लिए ठीक है; प्रोडक्शन में पोलिंग बेहतर है।
• जनरेशन एंडपॉइंट का जवाब आने में बहुत समय लग सकता है — क्लाइंट टाइमआउट 300 सेकंड या ज़्यादा रखें, और याद रखें कि "प्रतिक्रिया नहीं" और "कुछ बना नहीं" एक जैसे नहीं हैं; ऊपर "प्रतीक्षा समय और टाइमआउट सेटिंग" देखें।
• अपलोड, कवर, replace और WAV क्षमताएँ प्लेटफ़ॉर्म खातों और स्रोत क्लिप की अनुमतियों पर निर्भर हैं; विफल होने पर पहले लौटाया गया message या error_message पढ़ें।

इस दस्तावेज़ के बारे में

यह पेज उन क्षमताओं के अनुसार फिर से व्यवस्थित किया गया है जो Create UI वाकई दिखाता है, और नए इंटीग्रेशन को पहले इसे पढ़ना चाहिए। पुराने API दस्तावेज़ अब भी "पुराने API दस्तावेज़ (संगत)" अनुभाग में उन लोगों के लिए उपलब्ध हैं जो उन्हें इस्तेमाल करते रहना चाहते हैं।