वॉइस क्लोनिंग और निर्दिष्ट आवाज़ से जनरेशन API (सुझाया नहीं गया)

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

⛔ पुराना रास्ता, नई इंटीग्रेशन के लिए सुझाया नहीं जाता। यह पेज शुरुआती persona रास्ते (voice_task_id / generate-with-voice) का वर्णन करता है। यह अब भी काम करता है, लेकिन ग्राहकों को अब सुझाया नहीं जाता; बाईं ओर के मेन्यू में इसे "सुझाया नहीं गया" लिखा है।

नई इंटीग्रेशन के लिए 【सुझाया गया】 वॉइस प्रोफ़ाइल API इस्तेमाल करें: एक वोकल सैंपल से वॉइस प्रोफ़ाइल बनाएँ (POST /api/music/voice-profile/create), फिर उससे कोई तय गाना कवर करें या नया गाना गवाएँ। वॉइस प्रोफ़ाइल एक प्रथम-श्रेणी का संसाधन है: उसे सूचीबद्ध, पढ़ा और हटाया जा सकता है, और उसका स्रोत ऑडियो स्थायी रूप से सुरक्षित रहता है।

अगर आपके उत्पाद को "आवाज़ बनाएँ → लंबे समय तक दोबारा इस्तेमाल करें → कवर करें" का पूरा चक्र चाहिए, तो नए रास्ते को प्राथमिकता दें।

ज़रूरी बात: क्लोन की गई आवाज़ की अवधि खत्म हो सकती है।

वॉइस क्लोनिंग से बने voice_id / voice_task_id हमेशा के लिए चलने वाला संसाधन नहीं हैं: वैधता अवधि, अकाउंट की स्थिति या आवाज़ की स्थिति बदलने पर वे काम करना बंद कर सकते हैं। इंटीग्रेशन करने वाले को एक बार क्लोन करके स्थानीय कैश में रखी आवाज़ ID हमेशा दोबारा इस्तेमाल नहीं करनी चाहिए।

सुझाया तरीका:

• voice_task_id, voice_id, is_available, updated_at और आख़िरी सफल जनरेशन का समय सहेजें।
• क्लोन की गई आवाज़ से हर जनरेशन से पहले GET /api/voice/clone/tasks/{voice_task_id} या POST /api/voice/clone/tasks/{voice_task_id}/check कॉल करके is_available=true की पुष्टि करें।
• अगर एंडपॉइंट बताए कि आवाज़ उपलब्ध नहीं है, टास्क मौजूद नहीं है या selected voice is not ready लौटाए, तो यूज़र से दोबारा क्लोन करने या दूसरी उपलब्ध आवाज़ चुनने को कहें।
• अंतिम यूज़र से यह वादा न करें कि क्लोन की गई आवाज़ "स्थायी संपत्ति" है; प्रोडक्ट UI में बताएँ कि "आवाज़ की अवधि खत्म हो सकती है और दोबारा सत्यापन या दोबारा क्लोनिंग ज़रूरी हो सकती है"।

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

यह एंडपॉइंट समूह दोबारा इस्तेमाल हो सकने वाली आवाज़ बनाता है और उससे गाने बनाता है। कॉल करने वाले को सिर्फ़ प्लेटफ़ॉर्म का जारी किया API Key चाहिए; टास्क भेजना, स्टेटस सिंक, बिलिंग और डाउनलोड सर्वर खुद सँभालता है।

प्रमाणीकरण: Authorization: Bearer YOUR_API_KEY

बिलिंग:

• वॉइस वैलिडेशन, वॉइस क्लोनिंग, स्टेटस क्वेरी, डिलीट और डाउनलोड: मुफ़्त।
• वर्कस्पेस में एक-क़दम क्लोन का प्रवेश: प्रति कॉल 5 युआन तय; यह स्रोत आवाज़ का सत्यापन और दूसरा सत्यापन ऑडियो खुद पूरा करता है, और विफल होने पर रकम वापस कर देता है।
• सामान्य क्लोन के बाद सत्यापन ऑडियो अपने आप बनाना: प्रति कॉल 5 युआन तय; विफल होने पर मौजूदा प्रक्रिया के अनुसार वापसी होती है।
• क्लोन की गई आवाज़ से गाना बनाना: सशुल्क, प्रति कॉल 1.2 युआन तय; हर कॉल आम तौर पर 2 प्लेसहोल्डर टास्क लौटाती है।
• Max Mode चालू रहने पर (POST /api/music/generate-with-voice में max_mode: true), यह 1.2 युआन प्रति कॉल 2× की दर से यानी 2.4 युआन प्रति कॉल लगेगा; आवाज़ से जनरेशन variety भी सपोर्ट करता है (0-4, कोई अतिरिक्त शुल्क नहीं); मानों के नियम नई API का अवलोकन के "उन्नत पैरामीटर" हिस्से में हैं।

कॉल का क्रम

1. POST /api/voice/clone/validate कॉल करके स्रोत आवाज़ अपलोड करें और voice_task_id पाएँ।
2. GET /api/voice/clone/tasks/{voice_task_id} का इंतज़ार या पोलिंग करें और validate_info पाएँ।
3. यूज़र उस टेक्स्ट को पढ़कर सत्यापन ऑडियो रिकॉर्ड करता है।
4. POST /api/voice/clone/tasks/{voice_task_id}/generate कॉल करके सत्यापन ऑडियो भेजें।
5. POST /api/voice/clone/tasks/{voice_task_id}/check कॉल करें या टास्क पूछते रहें जब तक is_available=true न हो जाए।
6. POST /api/music/generate-with-voice कॉल करके उस आवाज़ से गाना बनाएँ।
7. जनरेशन एंडपॉइंट पहले प्लेसहोल्डर टास्क लौटाता है; जब जनरेशन पूरा हो और असली song_id मिल जाए, तो डाउनलोड एंडपॉइंट से एक फ़ाइल या एक पैकेज ले सकते हैं।
8. (वैकल्पिक) जब आवाज़ की ज़रूरत न रहे, तो DELETE /api/voice/clone/voices/{voice_task_id} कॉल करके हटा दें; अर्थ भाग 6 में है।

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

आवाज़ टास्क के फ़ील्ड

1. स्रोत आवाज़ सत्यापन के लिए भेजें

एंडपॉइंट: POST /api/voice/clone/validate

बॉडी पैरामीटर

vocal_end_s - vocal_start_s को वोकल सेगमेंट की न्यूनतम शर्त पूरी करनी चाहिए। साफ़, बिना स्पष्ट संगत या शोर वाली वोकल रिकॉर्डिंग अपलोड करें।

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

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "मेरी चीनी महिला आवाज़",
    "description": "साफ़ और स्वाभाविक चीनी महिला आवाज़",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

प्रतिक्रिया उदाहरण

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "मेरी चीनी महिला आवाज़",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. आवाज़ टास्क की क्वेरी

एंडपॉइंट: GET /api/voice/clone/tasks/{voice_task_id}

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

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

प्रतिक्रिया उदाहरण

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "मेरी चीनी महिला आवाज़",
      "validate_info": "यहाँ लौटाया गया सत्यापन टेक्स्ट पढ़कर सुनाएँ",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. सत्यापन टेक्स्ट दोबारा बनाएँ

एंडपॉइंट: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

जब सत्यापन टेक्स्ट पढ़ने के लिए उपयुक्त न हो या सत्यापन दोबारा करना हो, तब कॉल करें।

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. सत्यापन ऑडियो भेजें और आवाज़ बनाएँ

एंडपॉइंट: POST /api/voice/clone/tasks/{voice_task_id}/generate

बॉडी पैरामीटर

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

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "मेरी चीनी महिला आवाज़"
  }'

5. जाँचें कि आवाज़ उपयोग-योग्य है या नहीं

एंडपॉइंट: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

टास्क उपयोग-योग्य होने पर प्रतिक्रिया में is_available true होता है और voice_id लौटाया जाता है।

6. आवाज़ हटाएँ

एंडपॉइंट: DELETE /api/voice/clone/voices/{voice_task_id}

बिलिंग: मुफ़्त।

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

प्रतिक्रिया उदाहरण

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

हटाने के बाद क्या होता है

• नए गाने बनाने के लिए इस्तेमाल नहीं हो सकती: इस voice_task_id (या इसकी voice_id) के साथ POST /api/music/generate-with-voice कॉल करने पर अनुरोध अस्वीकार हो जाता है, संदेश selected voice is not ready होता है और कोई शुल्क नहीं लगता।
• इससे बने गानों पर कोई असर नहीं पड़ता: प्लेबैक, डाउनलोड, इस्तेमाल जारी रखना, बदलना और स्टेम अलग करना पहले जैसे चलते हैं।
• यह आवाज़ टास्क क्वेरी से गायब हो जाता है: GET /api/voice/clone/tasks/{voice_task_id} पर record not found मिलता है।
• स्रोत ऑडियो प्लेटफ़ॉर्म की स्थायी-संरक्षण नीति के तहत रखा जाता है (2026-09-23 से हटाने पर अपलोड किया गया वोकल सैंपल साफ़ नहीं होता), लेकिन इसका मतलब यह नहीं कि वह बहाल हो सकता है: वह पुराना टास्क खत्म हो चुका है, और वही आवाज़ जारी रखने के लिए क्लोन की पूरी प्रक्रिया दोबारा करनी होगी, जिससे नई voice_task_id मिलेगी।
• दोबारा हटाना: उसी टास्क को फिर हटाने पर record not found आता है (वह पहले से हटाई गई स्थिति में है और मिल नहीं सकती)।

7. क्लोन की गई आवाज़ से गाना बनाएँ

एंडपॉइंट: POST /api/music/generate-with-voice

बिलिंग: प्रति कॉल 1.2 युआन।

बॉडी पैरामीटर

suno-v6, suno-v6-wild और suno-v6-mini समर्थित हैं; खाली मॉडल को suno-v6 माना जाता है। पुराने V5/V5.5 मॉडल बंद कर दिए गए हैं, पर पुराने टास्क में अब भी पुराने नाम दिख सकते हैं।

साझा अनुरोध संरचना Create UI के संगतता फ़ील्ड जैसे task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId, voiceId भी पढ़ती है, पर ये इस एंडपॉइंट के मान्य ग्राहक पैरामीटर नहीं हैं: आवाज़ टास्क voice_task_id से भेजना ज़रूरी है, वैकल्पिक वॉइस सत्यापन voice_id से, और आवाज़ से संगीत जनरेशन sound फ़ील्ड कभी नहीं पढ़ता।

जनरेशन पैरामीटर भरने का तरीका

• customMode=false पर prompt में गाने का विवरण जाता है; customMode=true पर prompt में पूरे बोल, और style तथा title भी भरने होंगे। बोल को इंस्पिरेशन मोड के विवरण फ़ील्ड में न भेजें और गाने के विवरण को एडवांस्ड मोड के बोल न मानें।
• weirdnessConstraint और styleWeight 0.0 से 1.0 तक दशमलव अनुपात हैं; 50 या 50% नहीं भेज सकते। संतुलित मान 0.5 है; न भेजने का मतलब "तय नहीं" और 0 एक मान्य स्पष्ट मान है।
• vocalGender सिर्फ़ m, male, f या female लेता है। instrumental यहाँ केवल संगतता फ़ील्ड है: क्लोन आवाज़ से जनरेशन हमेशा गायन वाले गाने के रूप में लिया जाता है।
• waitAudio यहाँ व्यवहार नहीं बदलता; एंडपॉइंट हमेशा प्लेसहोल्डर टास्क असिंक्रोनस रूप से लौटाता है। शुरुआती नतीजे में खाली audio_url सामान्य है: client_request_id से क्वेरी करें और ऑडियो का पता नतीजा पूरा होने के बाद ही पढ़ें।

हेडर पैरामीटर

Idempotency-Key का व्यवहार:

• पहला अनुरोध बिलिंग से पहले एक स्थायी इडेम्पोटेंसी रिकॉर्ड लिखता है;
• अगर वही key और वही अनुरोध पहले ही पूरा हो चुका है, तो पहली स्वीकृति प्रतिक्रिया दोबारा दी जाती है, दूसरी बार शुल्क या दूसरा टास्क नहीं बनता;
• वही key अलग बॉडी के साथ अस्वीकार हो जाती है;
• वही key अब भी प्रोसेस में हो तो स्थिर "प्रोसेसिंग" त्रुटि आती है, और सुरक्षित client_request_id सिर्फ़ बन जाने पर लौटता है;
• किसी key से पहला अनुरोध विफल हो तो विफल स्थिति बनी रहती है; दोबारा कोशिश के लिए नई key चाहिए।

sourceClipId से कवर की शर्तें

ग्राहक API में स्रोत से कवर पूरा सर्वर साइड सँभालता है: स्रोत गाने तक पहुँच सर्वर तय करता है और ग्राहक कोई अकाउंट जानकारी नहीं भेजता। संभव है या नहीं, यह एंडपॉइंट की असल प्रतिक्रिया तय करती है।

स्रोत मौजूदा API यूज़र का होना चाहिए, वर्कस्पेस का पूरा हुआ गाना हो और pending: न हो, तथा उसका ऑडियो उपयोग-योग्य हो। सामान्य जनरेशन, सामान्य अपलोड के स्रोत और एन्हांस्ड अपलोड का अंतिम गाना समर्थित हैं; एन्हांस्ड अपलोड के बीच के रिकॉर्ड बिलिंग से पहले अस्वीकार हो जाते हैं। सर्वर सिर्फ़ ग्राहक द्वारा भेजी गई स्रोत-गाना ID लेता है, अकाउंट ID कभी नहीं; स्रोत उपलब्ध न हो या अधूरा हो तो बिलिंग से पहले त्रुटि मिलती है।

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

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "गर्मियों की रात में समुद्र किनारे पर एक चीनी पॉप गीत लिखें",
    "style": "Mandopop, warm piano, emotional",
    "title": "गर्मियों की रात की समुद्री हवा",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

प्रतिक्रिया उदाहरण

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "गर्मियों की रात की समुद्री हवा",
        "prompt": "गर्मियों की रात में समुद्र किनारे पर एक चीनी पॉप गीत लिखें"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "गर्मियों की रात की समुद्री हवा",
        "prompt": "गर्मियों की रात में समुद्र किनारे पर एक चीनी पॉप गीत लिखें"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

प्लेसहोल्डर टास्क और अंतिम song_id

generate-with-voice असिंक्रोनस जनरेशन एंडपॉइंट है। सफल प्रतिक्रिया का मतलब सिर्फ़ यह है कि जनरेशन टास्क भेज दिया गया है, यह नहीं कि गाना बन गया है।

प्रतिक्रिया के मुख्य फ़ील्ड का अर्थ:

ध्यान दें: pending: से शुरू होने वाला placeholder_id अंतिम song_id के रूप में इस्तेमाल नहीं हो सकता, और न ही सीधे /api/music/query या डाउनलोड एंडपॉइंट को दिया जा सकता है। सिर्फ़ pending:* मानों से /api/music/query कॉल करने पर खाली ऐरे [] लौट सकता है, क्योंकि असली गाना अभी बना नहीं है या प्लेसहोल्डर टास्क अभी अंतिम गाना ID से बदला नहीं गया।

ग़लत उदाहरण:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

सही क्रम:

1. POST /api/music/generate-with-voice कॉल करके आवाज़ वाला संगीत जनरेशन टास्क भेजें।
2. प्रतिक्रिया से client_request_id, items[].placeholder_id और items[].client_request_index सहेजें।
3. GET /api/music/generate-with-voice/results?client_request_id=cu_xxx पोल करें।
4. जब items[].song_id में मान आ जाए और वह pending: से शुरू न हो, तब /api/music/query, /api/music/download-file या /api/music/download-all कॉल करें।

मौजूदा वर्शन में एक सार्वजनिक क्वेरी एंडपॉइंट भी जोड़ा गया है:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

यह मौजूदा यूज़र के तहत उसी client_request_id के टास्क नतीजे लौटाता है, ताकि ग्राहक खुद अंतिम song_id ढूँढ सके। लौटी सूची में:

• song_id असली गाना ID है;
• placeholder_id तभी दिखता है जब टास्क अब भी प्लेसहोल्डर स्थिति में हो;
• pending: से शुरू होने वाला मान /api/music/query या डाउनलोड एंडपॉइंट के साथ इस्तेमाल नहीं हो सकता।

अगर आपने सिर्फ़ client_request_id या pending:* प्लेसहोल्डर ID सहेजी है, तो पहले यह नतीजा एंडपॉइंट कॉल करें; असली song_id फिर भी न मिले तो client_request_id टेक्निकल सपोर्ट को भेजकर पता लगवाएँ।

आवाज़ से जनरेशन के नतीजों की क्वेरी

एंडपॉइंट: GET /api/music/generate-with-voice/results

बिलिंग: मुफ़्त।

क्वेरी पैरामीटर

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

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

बनते समय प्रतिक्रिया उदाहरण

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "गर्मियों की रात की समुद्री हवा"
      }
    ]
  }
}

बन जाने पर प्रतिक्रिया उदाहरण

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "गर्मियों की रात की समुद्री हवा",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

ऊपरी स्तर के status का अर्थ

8. एक फ़ाइल डाउनलोड करें

एंडपॉइंट: 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": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

प्रतिक्रिया एक फ़ाइल स्ट्रीम है; Content-Type और फ़ाइल नाम बैकएंड जो लौटाए उसी पर चलते हैं।

9. गाने के संसाधन पैकेज में डाउनलोड करें

एंडपॉइंट: POST /api/music/download-all

बॉडी पैरामीटर

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

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": "song_abc123"
  }' \
  --output song.zip

पैकेज में आम तौर पर ऑडियो, कवर और metadata.json होता है; अगर किसी प्रकार का संसाधन अभी नहीं बना, तो वह संग्रह में नहीं आता।

आम त्रुटियाँ

इस समूह की त्रुटियाँ हमेशा HTTP 200 लौटाती हैं: सफलता बॉडी के success फ़ील्ड से तय करें (false यानी विफल, कारण message में) और सिर्फ़ HTTP स्टेटस कोड न देखें। आवाज़ हटाने का पूरा अर्थ (हटाने के बाद चलती है या नहीं, बहाल हो सकती है या नहीं) भाग 6 में है।