【सुझाया गया】 वॉइस प्रोफ़ाइल API

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

✅ नई इंटीग्रेशन के लिए हम यही रास्ता सुझाते हैं। बहुत से उपयोगकर्ताओं के असली आकलन के अनुसार, इस रास्ते से बने गाने मूल आवाज़ अच्छी तरह बनाए रखते हैं: तैयार ट्रैक की आवाज़ आपके अपलोड किए नमूने के व्यक्ति के ज़्यादा करीब होती है, इसलिए अभी यही रास्ता हम ग्राहकों को सुझाते हैं।

तुलना: पहले वाला वॉइस क्लोनिंग और निर्दिष्ट आवाज़ से जनरेशन API अब भी काम करता है, पर मेन्यू में उसे "सुझाया नहीं गया" लिखा है और नई इंटीग्रेशन के लिए वह सुझाया नहीं जाता।

• दस्तावेज़ की तारीख: 2026-09-26
• दायरा: अपनी आवाज़ बनाना → उससे किसी तय गाने का कवर करना / नया गाना गवाना → प्रगति देखना → नतीजा डाउनलोड करना
• दस्तावेज़ के सभी एंडपॉइंट, फ़ील्ड और प्रतिक्रियाएँ असली कॉल से जाँची गई हैं (जहाँ "मापा गया" लिखा है, वह विस्तार से जाँचा गया है)

ध्यान दें: यह दस्तावेज़ सिर्फ़ वे एंडपॉइंट बताता है जिन्हें आप कॉल करते हैं। सामग्री प्रोसेसिंग, टास्क शेड्यूलिंग और कंटेंट जाँच सर्वर अपने आप करता है; क्लाइंट को ये लागू नहीं करने।

0. पाँच मिनट में शुरुआत

चार क़दम काफ़ी हैं — एक वोकल सैंपल से दो तैयार गाने।

① आवाज़ बनाएँ   POST /api/music/voice-profile/create      → voice_id मिलेगा (status=ready)
② कवर करें      POST /api/music/voice-profile/cover       → तुरंत 2 song_id मिलेंगे
③ देखें         POST /api/music/query                     → status=completed तक पोल करें
④ डाउनलोड       GET  /api/music/download?song_id=…&kind=mp3

सबसे छोटा चलता उदाहरण (curl):

API_KEY="sk-aapki-chabi"
BASE="https://www.suno-api.io"

# ① आवाज़ बनाएँ (एक वोकल सैंपल अपलोड करें; 10 सेकंड या ज़्यादा, 10 MB से कम सुझाया गया)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=मेरी आवाज़" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② इस आवाज़ से एक गाना कवर करें (song_clip_id = जिस गाने को कवर करना है उसका clip id)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nगीत के बोल…",
        "style_requirements": "धीमा फ़ोक, अकॉस्टिक गिटार",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ पोल करें (कई id एक साथ, कॉमा से अलग करके)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ पूरा होने पर mp3 डाउनलोड करें (फ़ाइल सिर्फ़ status=completed पर मिलती है)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. सामान्य नियम

1.1 डोमेन और वातावरण

नीचे के सभी पाथ Base URL के सापेक्ष हैं; जैसे POST /api/music/voice-profile/create का पूरा पता https://www.suno-api.io/api/music/voice-profile/create है।

1.2 प्रमाणीकरण

सभी एंडपॉइंट एक ही रिक्वेस्ट हेडर इस्तेमाल करते हैं, जिसकी वैल्यू कंसोल में बनाई गई API Key होती है:

Authorization: Bearer sk-xxxxxxxx

• Bearer उपसर्ग हो या न हो; sk- उपसर्ग भी वैकल्पिक है (Authorization: sk-xxx भी चलता है)।
• कुंजी न हो या अमान्य हो → HTTP 401, बॉडी {"success":false,"message":"…"} जैसी (संदेश रिक्वेस्ट की भाषा के अनुसार बदलता है)।
• हर कुंजी सिर्फ़ अपने अकाउंट के गाने और आवाज़ें देख और बदल सकती है।

1.3 रिक्वेस्ट बॉडी के प्रारूप

• आवाज़ बनाना: multipart/form-data (फ़ाइल अपलोड) सुझाया गया; application/json (URL या base64) भी समर्थित।
• बाक़ी एंडपॉइंट: application/json।

1.4 दो रिस्पॉन्स खोल (ग्राहक को सिर्फ़ ये दो जानने हैं)

"आवाज़ प्रबंधन" वाले एंडपॉइंट (create / create-from-clip / list / detail / delete) बिज़नेस खोल इस्तेमाल करते हैं:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

"आवाज़ से कवर" जनरेशन चैनल से जाता है और जनरेशन खोल इस्तेमाल करता है: सफलता code/message/data, विफलता error ऑब्जेक्ट:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

कैसे तय करें: पहले HTTP स्टेटस कोड, फिर success === false, आख़िर में code !== 200 या error की मौजूदगी देखें। बिज़नेस विफलता से यह तय नहीं होता कि HTTP 200 नहीं होगा (आवाज़ प्रबंधन एंडपॉइंट गड़बड़ी पर भी HTTP 200 देते हैं), इसलिए सिर्फ़ स्टेटस कोड देखकर फ़ैसला न करें।

1.5 इडेम्पोटेंसी

आवाज़ बनाना ("मौजूदा ऑडियो से बनाना" समेत) वाक़ई इडेम्पोटेंट है: उसी कुंजी के नीचे वही client_request_id दोबारा भेजने पर सिर्फ़ एक आवाज़ बनती है और दूसरी कोशिश सीधे पहला नतीजा लौटाती है (success=true, वही voice_id)। तरीक़ा यह है कि क्लाइंट ख़ुद एक id बनाए (जैसे UUID) और टाइमआउट के बाद दोबारा कोशिश में वही वैल्यू इस्तेमाल करे।

कवर भेजना रिक्वेस्ट-स्तर पर डिडुप्लिकेशन नहीं करता (यह भुगतान वाली जनरेशन है), इसलिए दो बातें ध्यान रखें:

1. भेजने की पहचान हेडर X-Create-Ui-Client-Request-Id: <आपकी भेजने की id> में जाती है। यह सर्वर के टास्क रिकॉर्ड में लिखी जाती है ताकि बाद में जाँच आसान हो; पर यह दोहरे शुल्क को नहीं रोकती।
2. टाइमआउट ≠ विफलता: हो सकता है रिक्वेस्ट स्वीकार हो चुकी हो और जनरेशन चल रही हो। दोबारा कोशिश से पहले GET /api/music/songs?p=1&page_size=20 (पेजिंग के पैरामीटर p / page_size, और संगत लेखन ps भी) से देखें कि generation_type=voice_profile_cover वाला नया गाना आ चुका है या नहीं, और वही रिक्वेस्ट दोबारा तभी भेजें जब न आया हो।

create और create-from-clip की बॉडी में भी client_request_id फ़ील्ड है (§3 और §4)।

1.6 बिलिंग का सार

क़ीमतें कभी भी सार्वजनिक एंडपॉइंट से पढ़ी जा सकती हैं, इसलिए स्थिर न लिखें (§9 देखें):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← आवाज़ से कवर की आधार क़ीमत
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← प्रबलित क्लोन की क़ीमत
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

कवर पहले से शुल्क + विफलता पर वापसी पर चलता है:

• अस्वीकार की गई रिक्वेस्ट (ग़लत पैरामीटर, प्लेटफ़ॉर्म का 4xx/5xx, बैलेंस ख़ुद कम होना) पर शुल्क नहीं लगता — जो आवाज़ मौजूद नहीं है उससे भेजने पर हमारी माप में बैलेंस बिलकुल नहीं बदला (delta = 0);
• स्वीकार की गई पर आख़िर में विफल हुई टास्क (प्लेटफ़ॉर्म सेवा गड़बड़ी समेत) सर्वर की वापसी प्रक्रिया से गुज़रकर पहले लिया गया शुल्क लौटा देती है।

1.7 स्टेटस शब्दकोश

आवाज़ का status:

गाने का status (क्वेरी एंडपॉइंट क्या लौटाते हैं):

2. एंडपॉइंट का सार

3. आवाज़ बनाएँ

POST /api/music/voice-profile/create

एक वोकल ऑडियो को "आवाज़" के रूप में दर्ज करें और voice_id पाएँ। प्लेटफ़ॉर्म के लिए आवाज़ यानी "एक ऑडियो + कैटलॉग में उसका clip", इसलिए बनने के बाद वह स्रोत ऑडियो हमेशा के लिए सुरक्षित रहता है (आगे के कवर के लिए)।

3.1 तीन इनपुट रूप (कोई एक चुनें)

रूप A: multipart फ़ाइल अपलोड (सुझाया गया)

Content-Type: multipart/form-data

file=<ऑडियो बाइनरी>          # ज़रूरी
title=<आवाज़ का नाम>          # वैकल्पिक; ख़ाली हो तो बिना एक्सटेंशन फ़ाइल नाम
file_name=<मूल फ़ाइल नाम>
source_file_name=<मूल फ़ाइल नाम>
source_kind=upload|record    # वैकल्पिक, स्रोत चिह्न (अपलोड / रिकॉर्ड); डिफ़ॉल्ट upload
enhanced=false|true          # वैकल्पिक, true = प्रबलित क्लोन (§3.5 देखें)
client_request_id=<इडेम्पोटेंसी कुंजी>   # वैकल्पिक
voice_id=<अपनी id>            # वैकल्पिक, शायद ही इस्तेमाल हो

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=मेरी आवाज़" \
  -F "source_kind=upload"

रूप B: JSON + सार्वजनिक ऑडियो URL

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "मेरी आवाज़"
      }'

• URL सार्वजनिक रूप से खुला HTTPS सीधा लिंक होना चाहिए; सर्वर उसे एक बार डाउनलोड करके हमारे ऑब्जेक्ट स्टोरेज में रख देता है।
• पता audio_url फ़ील्ड में भी डाल सकते हैं, असर वही है (दोनों भेजें तो file_url प्राथमिक)।
• अगर पता पहले से इसी प्लेटफ़ॉर्म के ऑब्जेक्ट स्टोरेज में है (*.myqcloud.com/create-ui/voice-source/...), तो दोबारा डाउनलोड नहीं होता: सीधे दर्ज हो जाता है।

रूप C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "मेरी आवाज़"
}

• data:audio/xxx;base64, उपसर्ग और शुद्ध base64, दोनों समर्थित।
• आकार सीमित है (base64 1.33 गुना बढ़ाता है), बड़ी फ़ाइल के लिए रूप A इस्तेमाल करें।

3.2 ऑडियो की शर्तें

3.3 प्रतिक्रिया

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "मेरी आवाज़",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

फ़ील्ड की जानकारी (create / list / detail एक ही सेट साझा करते हैं):

created_at / updated_at सेकंड स्तर के टाइमस्टैम्प हैं (10 अंक), मिलीसेकंड नहीं।

3.4 आम ग़लतियाँ

3.5 प्रबलित क्लोन (enhanced=true)

उन मामलों के लिए जहाँ "सैंपल में ख़ुद कॉपीराइट वाले बोल हैं / प्रबलित अपलोड चाहिए"। क़ीमत प्रबलित अपलोड क़ीमत है (डिफ़ॉल्ट 10 युआन प्रति कॉल, विफलता पर अपने आप वापसी):

• प्रतिक्रिया तुरंत status=processing + task_id होती है (अभी clip_id नहीं) और काम असिंक्रोनस चलता है;
• चलते समय GET /api/music/voice-profile/{voice_id} से प्रगति देखें, जो progress_percent / progress_stage / progress_message लौटाता है;
• पूरा होने पर status ready हो जाता है और clip_id, audio_url, image_url भर जाते हैं;
• विफल हो तो status=failed और error_message लगभग "प्रबलित अपलोड विफल रहा; शुल्क अपने आप लौटा दिया गया, बाद में दोबारा कोशिश करें";
• प्रबलित क्लोन सामान्य बनाने से काफ़ी ज़्यादा समय लेता है (मिनटों में), इसलिए सिंक्रोनस टाइमआउट से इंतज़ार न करें।

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=मेरी आवाज़" -F "enhanced=true"

4. मौजूदा ऑडियो से आवाज़ बनाएँ

अगर दोबारा अपलोड नहीं करना: जो ऑडियो पहले ही अपलोड कर चुके हैं या बना चुके हैं उसे सीधे आवाज़ में कॉपी करें। मुफ़्त और इडेम्पोटेंट।

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: आपके अकाउंट में पूरा हो चुके ऑडियो का clip id (गाने के song_id के बराबर)।
• वही clip दोबारा भेजने पर नया रिकॉर्ड नहीं बनता: मौजूदा आवाज़ सीधे reused: true के साथ लौटती है (मापा गया)।

प्रतिक्रिया §3.3 के सारे फ़ील्ड और दो रीड-ओनली फ़ील्ड:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

ग़लतियाँ (message जैसा लौटता है; सीधे दिखाना या स्थानीयकृत करना सुझाया गया):

5. आवाज़ों की सूची / विवरण / हटाना

5.1 सूची

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "मेरी आवाज़", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

फ़ील्ड बिलकुल §3.3 जैसे हैं। डिफ़ॉल्ट में हटाई गई आवाज़ें नहीं लौटतीं।

5.2 विवरण

GET /api/music/voice-profile/{voice_id}

एक ही आवाज़ ऑब्जेक्ट लौटता है (data ख़ुद ऑब्जेक्ट है, ऐरे नहीं)। प्रबलित क्लोन चलते समय ये अतिरिक्त आते हैं:

5.3 हटाना

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• हटाने के बाद आवाज़ सूची से हट जाती है और नए कवर के लिए इस्तेमाल नहीं हो सकती: उस voice_id से भेजने पर 400 लौटता है (§6.4 देखें)।
• उससे पहले बने गानों पर कोई असर नहीं; प्लेबैक, डाउनलोड, आगे बढ़ाना, बदलना और अलग करना पहले जैसे चलते हैं।
• न मौजूद आवाज़, या इस अकाउंट की न होने वाली आवाज़ हटाने पर {"success":false,"message":"voice not found"} लौटता है।

6. आवाज़ से कवर (मुख्य एंडपॉइंट)

POST /api/music/voice-profile/cover
Content-Type: application/json

एक बार भेजने पर 2 गाने बनते हैं (सामान्य जनरेशन जैसे)।

6.1 दो परिदृश्य

प्रतिक्रिया में resolved_scene cover या sing लौटाता है, जिससे पता चलता है कौन सा रास्ता चला।

6.2 रिक्वेस्ट फ़ील्ड

हेडर X-Create-Ui-Client-Request-Id: <वही भेजने की id> भी भेजने की सलाह है: सिर्फ़ वही सर्वर टास्क रिकॉर्ड में लिखी जाती है और बाद की जाँच की मुख्य कुंजी बनती है (§1.5 देखें)।

इकाइयों का ध्यान: audio_weight / style_weight / weirdness_constraint 0–1 दशमलव, variety 0–4 पूर्णांक, duration सेकंड में। मिला देंगे तो रिजेक्ट या अजीब नतीजा मिलेगा।

परिदृश्य B में बोल वैकल्पिक हैं (मॉडल ख़ुद सँभालता है), पर जब तय सामग्री गवानी हो तो lyrics ज़रूर भेजें।

6.3 प्रतिक्रिया

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[कार्य] यह एक कवर है। … (सर्वर का तय ढाँचा + आपकी भरी कवर / स्टाइल शर्तें)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

मुख्य बातें:

1. तैयार ट्रैक की पहचान clips[].song_id से करें (यह एंडपॉइंट id फ़ील्ड नहीं लौटाता)।
2. तुरंत 2 song_id मिलते हैं, जबकि status अभी processing है (सिर्फ़ स्वीकार होने का मतलब) और audio_url ख़ाली; डाउनलोड से पहले completed तक पोल करना होगा। play_url प्लेटफ़ॉर्म की प्रीव्यू स्ट्रीम है, भेजते ही दिख सकती है और एक्सपायर हो जाती है।
3. description वह प्रॉम्प्ट है जो सर्वर आख़िर में भेजता है (तय ढाँचा + आपके cover_requirements / style_requirements); नतीजा जाँचते समय बहुत काम आता है।
4. source_updates सर्वर की सामग्री प्रोसेसिंग का नतीजा है, क्लाइंट इसे छोड़ सकता है।
5. आपका भेजा title सर्वर टास्क रिकॉर्ड में जाता है और आगे की क्वेरी में song_title बनकर दिखता है; भेजते समय clips[].song_title का ख़ाली होना सामान्य है।

6.4 ग़लतियाँ

{ "error": { "message": "यह आवाज़ मौजूद नहीं है या हटा दी गई है (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

कम बैलेंस भेजते ही बिलिंग गड़बड़ी लौटाता है और आधा-अधूरा टास्क नहीं छोड़ता।

6.5 उपलब्ध मॉडल (ग्राहक-मुखी नाम)

ग्राहक-मुखी मॉडल नाम (ऊपर वाले) इस्तेमाल करें। chirp-* प्लेटफ़ॉर्म के आंतरिक नाम हैं, सीधे इस्तेमाल न करें।

7. प्रगति देखना

7.1 सामूहिक क्वेरी (सुझाया गया)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids कॉमा से अलग किया गया स्ट्रिंग है (ऐरे नहीं)।
• प्रतिक्रिया खुला ऐरे है (सीधे [...], success / data खोल के बिना):

[
  {
    "song_id": "0f2a…",
    "song_title": "दो बाघ",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[कार्य] यह एक कवर है। … (सर्वर का अंतिम प्रॉम्प्ट)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

पोलिंग की सलाह: हर 5–10 सेकंड, कुल टाइमआउट 10–15 मिनट (सबसे धीमा ठंडा अकाउंट माप में लगभग 4.5 मिनट; बहुत कम ज़्यादा)। पूरा होना audio_url ख़ाली होने से नहीं, status से तय करें।

संगतता नोट: यह एंडपॉइंट गानों की पहचान song_id से करता है; शुरुआती कुछ प्रतिक्रियाओं में id फ़ील्ड आया था, इसलिए row.song_id || row.id सुरक्षित तरीक़ा है।

7.2 एक गाने का विवरण

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "दो बाघ",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "दो बाघ",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• यहाँ created_at / completed_at Unix सेकंड हैं (सामूहिक क्वेरी की ISO स्ट्रिंग से अलग, क्लाइंट को फ़र्क़ समझना चाहिए)।
• wav_url / video_url इस प्लेटफ़ॉर्म के डाउनलोड द्वार हैं (मौजूदा डोमेन के सापेक्ष) और GET से फ़ाइल मिलती है; प्लेटफ़ॉर्म ने वह उत्पाद न बनाया हो तो ख़ाली स्ट्रिंग होती है।
• parameter_retention बताता है कि उस गाने को किन भेजे गए पैरामीटर तक ट्रेस किया जा सकता है: core_parameters_available=true का मतलब बोल / स्टाइल / स्रोत जैसे मुख्य पैरामीटर पूछे जा सकते हैं, और extended_parameters_available=false पर ऊपर दिए विस्तारित पैरामीटर सुरक्षित नहीं रखे गए (आवाज़ से कवर इस समय इसी श्रेणी में हैं)।

7.3 मेरे काम

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=कीवर्ड

पेजिंग: p (पेज नंबर, 1 से) / page_size (प्रति पेज संख्या; संगत लेखन ps)। वैकल्पिक status और q (शीर्षक का कीवर्ड)। डिफ़ॉल्ट में बनाने के समय के उलटे क्रम में।

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "दो बाघ",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

generation_type=voice_profile_cover से "आवाज़ से कवर बने गाने" और बाक़ी जनरेशन नतीजों को अलग पहचान सकते हैं।

8. तैयार गाने डाउनलोड करना

8.1 सीधे mp3 लेना (सुझाया गया, मुफ़्त)

तीनों तरीक़े चलते हैं; कोई एक चुनें:

1. क्वेरी नतीजे का audio_url इस्तेमाल करें (ऑब्जेक्ट स्टोरेज का सीधा लिंक, सबसे आसान)।
2. GET /api/music/download?song_id=<id>&kind=mp3 → सीधे ऑडियो बाइट स्ट्रीम लौटाता है (Content-Disposition में फ़ाइल नाम मौजूद)।
3. POST /api/music/download-url (हस्ताक्षरित अस्थायी पता लेने के लिए)।

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

kind मान: mp3 (song के बराबर) / playback (स्ट्रीमिंग प्लेबैक) / wav / video / lyrics / timestamped_lyrics। timestamped_lyrics (.lrc) अभी सिर्फ़ कुछ गानों पर उपलब्ध है; विफल हो तो टाइमस्टैम्प वाला गीत API से ख़ुद बनाएँ। प्रतिक्रिया सीधे फ़ाइल की बाइट स्ट्रीम है, Content-Type और Content-Disposition (फ़ाइल नाम) पहले से सेट हैं; GET /api/music/songs/{song_id} जो wav_url / video_url देता है वही द्वार kind=wav|video के साथ है।

8.2 wav में बदलना / बोल / मेटाडेटा (शुल्क सहित)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files ये लेता है: mp3 / wav / lyrics / metadata, एक बार में ज़्यादा से ज़्यादा 10 गाने।
• सफल गानों की संख्या पर शुल्क (0.2 युआन प्रति गाना); पूरा विफल गाना नहीं गिना जाता, और विफल फ़ॉर्मैट सिर्फ़ songs[].errors में दिखता है।
• पहले डाउनलोड किए फ़ाइल दोबारा लेने के लिए पहले मुफ़्त POST /api/music/free2/cached (वही song_ids + files) से संग्रहित पता लें; उसकी प्रतिक्रिया में songs[].missing_files वे फ़ॉर्मैट बताता है जो कैश में नहीं हैं और दोबारा तैयार करने होंगे।

9. क़ीमत पूछना

GET /api/pricing/catalog

प्रमाणीकरण की ज़रूरत न रखने वाला सार्वजनिक एंडपॉइंट। ग्राहक को दिखाने वाली सारी इकाई क़ीमतें data.catalog.meta (स्ट्रिंग) में हैं:

क़ीमतें बैक-ऑफ़िस में बदलती हैं, इसलिए लाइव पढ़ें, क्लाइंट में स्थिर न लिखें। कवर का असली शुल्क = voice_generation_price × (max_mode सही हो तो एक बार और max_mode_factor)।

10. सीमाएँ और चेतावनियाँ

1. अपलोड का आकार: ≤ 10 MB (सर्वर ज़्यादा लेता है, पर प्रवेश गेटवे 10 MiB पर बड़ी बॉडी काट देता है और "Suno ने अस्वीकार किया" जैसा दिखता है; अपनी तरफ़ पहले रोकें)।
2. सैंपल की लंबाई: कम से कम 6 सेकंड, 10–60 सेकंड सुझाया गया; बहुत छोटा हो तो प्लेटफ़ॉर्म अस्वीकार करता है।
3. सैंपल की सामग्री: साफ़ वोकल; जो मौजूदा रिकॉर्डिंग से बहुत मिलता हो उससे बचें (कैटलॉग तुलना उसे अस्वीकार करती है)।
4. पाठ की सीमाएँ: lyrics ≤ 3000 अक्षर; style_requirements / negative_tags / title क्रमशः 1000 / 1000 / 100 अक्षरों में रखना बेहतर (स्टाइल और कवर की शर्तें प्रॉम्प्ट में जुड़ती हैं, कुल 3000 अक्षरों में रखें)।
5. बोल बदले नहीं जाते: जो भेजेंगे वही गाया जाएगा (अक्षर-दर-अक्षर), स्थानीय कटौती नहीं होती।
6. हर गाना 2 ट्रैक देता है; एक नतीजा मानकर न चलें।
7. स्रोत ऑडियो हमेशा सुरक्षित: आवाज़ हटाने से उसका स्रोत ऑडियो साफ़ नहीं होता; इससे आगे के कवर मुमकिन रहते हैं और अनुपालन ट्रेस करने योग्य रहता है।
8. आवाज़ ready होनी चाहिए: processing आवाज़ कवर में नहीं चलती।
9. रिक्वेस्ट टाइमआउट: ठंडे अकाउंट पर पहली बार भेजना माप में लगभग 4.5 मिनट तक लगा, इसलिए क्लाइंट टाइमआउट ≥ 6 मिनट रखें। कवर रिक्वेस्ट-स्तर पर डिडुप्लिकेशन नहीं करता, इसलिए टाइमआउट के बाद पहले देखें कि नया गाना बन चुका है या नहीं (§1.5), फिर दोबारा भेजने का फ़ैसला करें।
10. आवाज़ का स्वामित्व: आवाज़ें बनाने वाले की होती हैं; कवर सिर्फ़ तैयार और न हटाई गई आवाज़ें स्वीकार करता है। मौजूद न हो, हटाई गई हो या दूसरे अकाउंट की हो तो 400 लौटता है: यह आवाज़ मौजूद नहीं है या हटा दी गई है (voice_id=…)।

11. अक्सर पूछे जाने वाले सवाल (FAQ)

प्र1. आवाज़ बनाने में ख़र्च लगता है? सामान्य बनाना और "मौजूदा ऑडियो से बनाना" मुफ़्त हैं; शुल्क सिर्फ़ कवर (1.2 युआन / MAX 2.4 युआन) और प्रबलित क्लोन (डिफ़ॉल्ट 10 युआन) पर लगता है।

प्र2. संगीत के साथ तैयार गाना सैंपल के तौर पर चलेगा? नहीं सुझाया गया। जिसमें संगीत हो या जो कैटलॉग की मौजूदा रिकॉर्डिंग से बहुत मिलता हो, प्लेटफ़ॉर्म अस्वीकार करता है (This audio matches an existing recording in our catalog.)। शुद्ध सूखा वोकल लें।

प्र3. कवर भेजने के बाद audio_url ख़ाली क्यों? भेजना सिर्फ़ स्वीकार होने का मतलब है और status अभी processing है। चलाने/डाउनलोड करने लायक पता तभी मिलता है जब /api/music/query को status=completed तक पोल किया जाए।

प्र4. परिदृश्य B (song_clip_id नहीं) में बोल भेजें? वैकल्पिक। तय सामग्री गवानी हो तो lyrics भेजें; न भेजें तो मॉडल ख़ुद सँभालता है, पर नियंत्रण कम रहता है।

प्र5. ग्राहक का अपलोड किया ऑडियो सीधे आवाज़ बन सकता है? हाँ: create के file_url रूप से, या पहले उसे गाने के रूप में अपलोड करके फिर create-from-clip कॉल करके।

प्र6. विफल होने पर पैसे वापस मिलते हैं? सीधे अस्वीकार की गई रिक्वेस्ट (ग़लत पैरामीटर / प्लेटफ़ॉर्म त्रुटि) पर माप के अनुसार शुल्क नहीं लगता; स्वीकार की गई पर आख़िर में विफल हुई टास्क पहले लिया शुल्क लौटा देती है। अंतिम विफलता पर टास्क status=failed और error_message लौटाता है।

प्र7. आवाज़ हटाने के बाद उससे बने गाने सुन सकते हैं? हाँ। हटाना सिर्फ़ इस पर असर डालता है कि वह आवाज़ नए कवर में चलेगी या नहीं।

प्र8. एक बार में कितना लंबा गाना कवर हो सकता है? duration 1–480 सेकंड लेता है; न भेजें तो प्लेटफ़ॉर्म मूल गाने / सामग्री से तय करता है। ध्यान: प्लेटफ़ॉर्म के तैयार ट्रैक कम से कम लगभग 30 सेकंड के होते हैं; 30 सेकंड से छोटी वैल्यू भी माप में 29.96 / 29.76 सेकंड ही देती रही।

परिशिष्ट A: पूरा उदाहरण (Node.js, पोलिंग और डाउनलोड समेत)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① आवाज़ बनाएँ (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② कवर
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "धीमा फ़ोक, अकॉस्टिक गिटार",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ पूरा होने तक पोल करें (हर 5 सेकंड, ज़्यादा से ज़्यादा 15 मिनट)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // खुला ऐरे
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ डाउनलोड
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "मेरी आवाज़");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nबोल…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

परिशिष्ट B: बदलाव का रिकॉर्ड