कस्टम मोड जनरेशन API

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

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

कस्टम मोड तब उपयुक्त है जब बोल, स्टाइल और शीर्षक तैयार हों और आप गाने वाली आवाज़, स्टाइल के प्रभाव की तीव्रता और जनरेशन की यादृच्छिकता को नियंत्रित करना चाहें।

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

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

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 का अवलोकन में "प्रतीक्षा समय और टाइमआउट सेटिंग" देखें।

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

Headers

Body पैरामीटर

उन्नत पैरामीटर नोट

आवाज़ का लिंग vocal_gender

• पुरुष आवाज़ के लिए m या male, महिला आवाज़ के लिए f या female भेजें।
• सेवा male और female को क्रमशः m और f में सामान्यीकृत करती है।
• instrumental=true होने पर जनरेशन सेवा को आवाज़ के लिंग का पैरामीटर नहीं भेजा जाता।

स्टाइल प्रभाव style_weight

नियंत्रित करता है कि नतीजा style_tags का कितनी मज़बूती से पालन करता है। मान जितना ऊँचा, नतीजा उतना ही आपके दिए स्टाइल टैग की ओर झुकता है।

यादृच्छिकता weirdness_constraint

नियंत्रित करता है कि नतीजा कितना बदलता और प्रयोगात्मक रहता है। ऊँचे मान आम तौर पर ज़्यादा विविधता देते हैं; नीचे मान ज़्यादा सुरक्षित नतीजा।

दोनों संख्यात्मक पैरामीटर 0.0 से 1.0 के बीच हैं, और 0 एक वैध स्पष्ट मान है। केवल फ़ील्ड पूरी तरह छोड़ना ही "निर्दिष्ट नहीं" दर्शाता है।

भरते समय ध्यान रखें कि ये दशमलव भिन्न हैं, प्रतिशत के पूर्णांक नहीं। सुझाया संदर्भ: 0.0–0.3 रूढ़िवादी, 0.4–0.6 संतुलित, 0.7–1.0 अधिक प्रयोगात्मक; स्पष्ट पसंद न हो तो 0.5 इस्तेमाल करें या इन्हें छोड़ दें। उदाहरण: weirdness_constraint: 0.5, कभी 50 या 50% न लिखें।

instrumental=true पर नतीजा वाद्य होता है, इसलिए बोल और आवाज़ का लिंग गाए गए गाने की तरह काम नहीं करते; आवाज़ चाहिए तो false भेजें या वह फ़ील्ड छोड़ दें। बूलियन फ़ील्ड में JSON के true/false इस्तेमाल करें, स्ट्रिंग नहीं।

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

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nरात समुद्र पर उतरती है\nशाम की हवा खिड़की से गुज़रती है',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'समुद्र किनारे शाम की हवा',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

रसीद-स्वीकृति मोड (वैकल्पिक)

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

यह उन क्लाइंट के लिए उपयुक्त है जिन्हें लंबा कनेक्शन नहीं रखना चाहिए, या जो नहीं चाहते कि टाइमआउट को "कुछ नहीं बना" समझा जाए। यह पैरामीटर न देने पर व्यवहार पहले जैसा ही है।

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "समुद्र किनारे शाम की हवा",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

प्रतिक्रिया का स्वरूप और पोलिंग का तरीका सरल मोड जनरेशन API के "रसीद-स्वीकृति मोड" भाग में है।

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

ये मामले HTTP 400 लौटाते हैं, और त्रुटि का message अमान्य फ़ील्ड बताता है:

• style_weight या weirdness_constraint संख्या नहीं है।
• कोई संख्यात्मक मान 0.0 से कम या 1.0 से ज़्यादा है।
• vocal_gender m, f, male, female में से एक नहीं है।

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

ये फ़ील्ड भी ज़्यादा लंबे होने पर HTTP 400 लौटाते हैं, जनरेशन में नहीं जाते और अग्रिम शुल्क नहीं कटता। गिनती Unicode अक्षरों में है (एक हान अक्षर 1) और आरंभ/अंत की स्पेस भी गिनी जाती हैं:

त्रुटि संदेश style_tags must not exceed 1000 characters; received 2772 जैसा होता है: पहला शब्द सीमा पार करने वाला फ़ील्ड है और अंत में मापी गई संख्या, इसलिए 400 मिलने पर उन्हीं दो संख्याओं से काटें, फ़ील्ड दर फ़ील्ड आज़माने की ज़रूरत नहीं। सामान्य नियम नए API का अवलोकन के "टेक्स्ट फ़ील्ड की सीमाएँ" में हैं।

प्रतिक्रिया

एंडपॉइंट आम तौर पर 2 गानों वाली सरणी लौटाता है। असिंक्रोनस अनुरोध आम तौर पर pending स्थिति से शुरू होता है; song_id सहेजें और अंतिम स्थिति तथा ऑडियो पता गाना क्वेरी API से लें। गाने के फ़ील्ड सरल मोड जनरेशन API जैसे ही हैं।

संगत फ़ील्ड

नए इंटीग्रेशन हर जगह snake_case इस्तेमाल करें। अगर एक ही अनुरोध में snake_case और camelCase दोनों हों, तो snake_case का मान मान्य होता है।