गाना क्वेरी और इतिहास API

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

इस पेज में तीन मुफ़्त क्वेरी एंडपॉइंट हैं:

क्षमता	Method	एंडपॉइंट
किसी गाने की स्थिति और नतीजा पूछना	POST	`/api/music/query`
मौजूदा खाते के बनाए गाने पूछना	GET	`/api/music/songs`
गाना बनाते समय सहेजे गए पैरामीटर पूछना	GET	`/api/music/songs/:song_id`

अगर आपने जनरेशन एंडपॉइंट पर रसीद-स्वीकृति मोड (accept_mode=async) इस्तेमाल किया है, तो आपके पास गाना ID नहीं बल्कि रसीद संख्या है। प्रगति GET /api/music/requests/{request_id} से देखें और असली song_id मिलने के बाद इस पेज के एंडपॉइंट पर लौटें। सरल मोड जनरेशन API में "रसीद-स्वीकृति मोड" देखें।

प्रमाणीकरण और डेटा दायरा

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

Authorization: Bearer YOUR_API_KEY

गानों का इतिहास उस user_id के हिसाब से अलग रहता है जिसका API कुंजी है। एक ही मुख्य खाते के तहत बनी कई API कुंजियाँ उस खाते का इतिहास पढ़ सकती हैं, पर किसी दूसरे उपयोगकर्ता या सबसाइट खाते के गाने नहीं।

इतिहास वाले एंडपॉइंट केवल असल में बने गाने लौटाते हैं। इन्हें शामिल नहीं किया जाता:

pending: से शुरू होने वाले जनरेशन प्लेसहोल्डर रिकॉर्ड;
स्रोत ऑडियो अपलोड और एन्हांस्ड अपलोड रिकॉर्ड;
वोकल/संगीत अलगाव और स्टेम जैसे उप-नतीजे;
दूसरे उपयोगकर्ताओं या सबसाइट खातों के गाने।

1. जनरेशन स्थिति पूछना

एक या अधिक गाना ID की मौजूदा स्थिति और अंतिम नतीजा देखता है।

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

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

Headers

पैरामीटर	प्रकार	ज़रूरी	नोट
Authorization	string	हाँ	`Bearer YOUR_API_KEY`
Content-Type	string	हाँ	`application/json`

Body पैरामीटर

पैरामीटर	प्रकार	ज़रूरी	डिफ़ॉल्ट	नोट
model	string	नहीं	`suno-v6`	मॉडल संस्करण
song_ids	string	हाँ	-	गाना ID, कॉमा से अलग

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

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

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

[
  {
    "song_id": "clip_id_1",
    "song_title": "गाने का शीर्षक",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "गीत के बोल",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

संगतता नोट

पुराने दस्तावेज़ song_ids को सरणी की तरह दिखा सकते हैं। आज कॉमा से अलग स्ट्रिंग की सलाह दी जाती है, जो एंडपॉइंट को असल में कॉल करने के तरीके से मेल खाती है।

song_ids में असली गाना ID होने चाहिए। pending: से शुरू होने वाला प्लेसहोल्डर ID अंतिम song_id नहीं है और यहाँ इस्तेमाल नहीं हो सकता; केवल प्लेसहोल्डर ID पूछने पर खाली सरणी [] मिल सकती है।

प्रतिक्रिया में model, model_version या प्लेटफ़ॉर्म का model_name ऐतिहासिक मान रख सकते हैं। नए कामों के लिए suno-v6, suno-v6-wild या suno-v6-mini इस्तेमाल करें; suno-v2 से suno-v5-5 तक हटा दिए गए हैं, और इतिहास में ये नाम दिखना इस बात का सबूत नहीं कि वह मॉडल अब भी भेजा जा सकता है।

जब तक कोई काम pending, submitted या processing में है, audio_url, video_url और cover_url खाली हो सकते हैं — अधूरे काम के लिए यह सामान्य है। सिर्फ़ खाली पते से निष्कर्ष न निकालें; status देखें और स्थिति पूरी होने पर फिर क्वेरी करें। केवल तब, जब स्थिति पूरी हो और पते फिर भी खाली हों, song_id के साथ सहायता टीम से संपर्क करना ठीक है।

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

यहाँ लौटाए गए audio_url, video_url (और WAV जैसे अन्य मीडिया पते) प्लेटफ़ॉर्म के ऑब्जेक्ट स्टोरेज से दिए जाते हैं और डिफ़ॉल्ट रूप से 7 दिन बाद समाप्त हो जाते हैं: फ़ाइलें रीसाइकल हो जाती हैं और पुराना पता 404 देता है।

उन 7 दिनों में फ़ाइलें अपने स्टोरेज में ले जाएँ; इस पते को दीर्घकालिक लिंक न मानें।

समाप्त पते के लिए गाना दोबारा बनाने की ज़रूरत नहीं और दोबारा शुल्क नहीं: उस गाने का नया वैध पता पाने के लिए यह एंडपॉइंट (POST /api/music/query) फिर से कॉल करें।

2. खाते का गाना इतिहास पूछना

मौजूदा API कुंजी के मुख्य खाते ने जो गाने बनाए हैं, उन्हें सूचीबद्ध करता है। अपनी गाना सूची, चयनकर्ता या इतिहास पेज बनाने के लिए उपयुक्त।

एंडपॉइंट: GET /api/music/songs

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

Query पैरामीटर

पैरामीटर	प्रकार	ज़रूरी	डिफ़ॉल्ट	नोट
p	integer	नहीं	`1`	पेज नंबर, 1 से शुरू
page_size	integer	नहीं	`20`	प्रति पेज आइटम, अधिकतम 100
q	string	नहीं	-	शीर्षक से अस्पष्ट खोज, या पूरे गाना ID से सटीक खोज
status	string	नहीं	-	स्थिति से सटीक फ़िल्टर, जैसे `completed`, `playable`

नतीजे created_at और आंतरिक रिकॉर्ड ID के घटते क्रम में लगते हैं, इसलिए पेजिंग का क्रम स्थिर रहता है।

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

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

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "रात का शहर",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

प्रतिक्रिया फ़ील्ड

फ़ील्ड	प्रकार	नोट
song_id	string	असली गाना ID, विवरण क्वेरी में इस्तेमाल हो सकता है
title	string	मौजूदा शीर्षक, जिसे उपयोगकर्ता ने बदला हो सकता है
status	string	मौजूदा स्थिति
generation_type	string	जनरेशन का प्रकार
model	string	जनरेशन मॉडल
duration	number	ऑडियो की अवधि सेकंड में
audio_url	string	ऑडियो पता; पूरा होने तक खाली हो सकता है
image_url	string	कवर पता; खाली हो सकता है
created_at	integer	बनाने का समय, सेकंड में Unix टाइमस्टैम्प
completed_at	integer	पूरा होने का समय, सेकंड में Unix टाइमस्टैम्प; पूरा होने तक न हो

सूची एंडपॉइंट प्रॉम्प्ट, बिलिंग फ़ील्ड, खाता जानकारी या कच्ची प्रतिक्रिया नहीं लौटाता। प्रॉम्प्ट और जनरेशन पैरामीटर के लिए गाना विवरण एंडपॉइंट कॉल करें।

3. जनरेशन पैरामीटर पूछना

गाना बनाते समय प्लेटफ़ॉर्म ने जो प्रॉम्प्ट, स्टाइल, मॉडल और स्रोत गाना सहेजा था, वह देखता है।

एंडपॉइंट: GET /api/music/songs/:song_id

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

केवल मौजूदा API कुंजी के मुख्य खाते के गाने पढ़े जा सकते हैं। दूसरे उपयोगकर्ताओं या सबसाइट खातों के गाने एक जैसे "गाना नहीं मिला" माने जाते हैं।

पाथ पैरामीटर

पैरामीटर	प्रकार	ज़रूरी	नोट
song_id	string	हाँ	असली गाना ID

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

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "रात का शहर",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "बारिश के बाद शहर की सड़कें, फिर मिलने पर बोल",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "रात का शहर",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

`parameters` फ़ील्ड

फ़ील्ड	प्रकार	नोट
prompt	string	जनरेशन प्रॉम्प्ट या बोल
style_tags	string	स्टाइल टैग
title	string	सहेजा गया जनरेशन शीर्षक; सामान्य इतिहास कार्य में केवल मौजूदा शीर्षक बचा हो सकता है
model	string	जनरेशन मॉडल
generation_type	string	जनरेशन का प्रकार
source_song_id	string	कवर, विस्तार और ऐसे कार्यों का स्रोत गाना ID
source_audio_url	string	स्रोत ऑडियो पता
custom_mode	boolean/null	कस्टम मोड इस्तेमाल हुआ या नहीं; सहेजा न गया हो तो `null`
instrumental	boolean/null	गाना वाद्य-मात्र है या नहीं; मौजूदा इतिहास डेटा आम तौर पर इसे अलग नहीं सहेजता
negative_tags	string/null	बाहर रखे गए स्टाइल
vocal_gender	string/null	वोकल जेंडर सेटिंग
lyrics_mode	string/null	बोल मोड; मौजूदा इतिहास डेटा आम तौर पर इसे नहीं सहेजता
wait_audio	boolean/null	पूरे ऑडियो का इंतज़ार हुआ या नहीं; मौजूदा इतिहास डेटा आम तौर पर इसे नहीं सहेजता
style_weight	number/null	स्टाइल भार
weirdness_constraint	number/null	रचनात्मकता/विचित्रता पैरामीटर

`prompt_view` फ़ील्ड (प्रॉम्प्ट देखें, 2026-09-28 को जोड़ा गया)

prompt_view "प्रॉम्प्ट देखें" के लिए बनी सामान्यीकृत संरचना है: यह जनरेशन प्रकार के हिसाब से डेटा को तय खंडों में रखती है, ताकि क्लाइंट को यह तय न करना पड़े कि कौन-सा फ़ील्ड दिखाना है। यह केवल जोड़ने वाला फ़ील्ड है — पुराने फ़ील्ड (parameters, parameter_retention) नाम और अर्थ वही रखते हैं, और नए फ़ील्ड को न पढ़ने वाले क्लाइंट पर कोई असर नहीं पड़ता।

"prompt_view": {
  "type": "custom_generate",
  "type_label": "कस्टम मोड",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "सुबह के चार बजे#701f37", "title_base": "सुबह के चार बजे", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "गुओचाओ इलेक्ट्रॉनिक, गहरा सब बेस, रेट्रो सिंथ",
    "style_tags": "गुओचाओ इलेक्ट्रॉनिक, गहरा सब बेस, रेट्रो सिंथ",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

फ़ील्ड	प्रकार	नोट
`type` / `type_label`	string	कच्चा जनरेशन प्रकार / दिखने वाला लेबल (सरल जनरेशन, कस्टम मोड, साउंड इफ़ेक्ट मोड, क्लोन आवाज़ से जनरेशन…)
`generation.model`	string	इस्तेमाल किया गया मॉडल
`generation.max_mode`	bool	Max Mode चालू था या नहीं
`generation.duration`	number	ऑडियो अवधि (सेकंड)
`generation.title`	string	जैसा सहेजा गया शीर्षक (प्रत्यय सहित हो सकता है)
`generation.title_base`	string	अंत का `#xxxxxx` प्रत्यय हटाकर दिखने वाला शीर्षक
`generation.title_suffix`	string	प्रत्यय स्वयं (`#` के बिना); न हो तो खाली
`inputs.user_text`	string	उपयोगकर्ता का इनपुट (प्रकार के अनुसार विवरण या बोल)
`inputs.user_text_kind`	string	`lyrics` / `description` / `cover_requirements`
`inputs.user_style`	string	उपयोगकर्ता ने खुद लिखा स्टाइल (कस्टम मोड, आवाज़, साउंड इफ़ेक्ट)
`inputs.style_tags`	string	आख़िर में लागू हुआ स्टाइल
`inputs.style_source`	string	`user` = उपयोगकर्ता ने लिखा; `suno_derived` = Suno ने विवरण से निकाला
`inputs.lyrics`	string	बोल का पाठ; न हों तो खाली, वाद्य गाने में `[Instrumental]`
`inputs.negative_tags`	string	बाहर रखे गए स्टाइल
`inputs.is_instrumental`	bool	गाना वाद्य-मात्र है या नहीं
`extended.*`	—	विस्तारित पैरामीटर, नीचे देखें; न सहेजे गए फ़ील्ड नहीं दिखते
`reference.voice_name`	string	आवाज़ का नाम (केवल आवाज़ प्रकारों में; आंतरिक persona id नहीं लौटाया जाता)
`reference.source_song_id` / `source_title`	string	कवर, विस्तार और ऐसे कार्यों का स्रोत गाना
`retention.recorded_since`	string	विस्तारित पैरामीटर सहेजने की शुरुआत की तारीख़ (`2026-09-28`)
`retention.missing_reason`	string	विस्तारित पैरामीटर क्यों नहीं; इतिहास डेटा में `not_recorded_before_20260928`
`retention.not_applicable_fields`	string[]	वे पैरामीटर जो उस जनरेशन प्रकार को कभी ज़रूरी नहीं थे (इन्हें "पैरामीटर गायब" के रूप में न दिखाएँ)

extended में दिख सकने वाले फ़ील्ड: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, और साउंड इफ़ेक्ट समूह sound_type / sound_bpm / sound_key / sound_loop. खाली मान कभी नहीं लौटाए जाते।

तीन प्रदर्शन नियम (अंदाज़ा लगाने के बजाय इन्हें मानें):

स्टाइल का स्रोत अलग पहचानें: जब style_source=suno_derived हो, तो "स्टाइल (Suno ने आपके विवरण से निकाला)" दिखाएँ, "आपका लिखा स्टाइल" न लिखें;
आंतरिक प्रॉम्प्ट कभी नहीं दिखते: आवाज़-कवर प्रकार केवल उपयोगकर्ता द्वारा लिखे 【स्टाइल आवश्यकताएँ】/【कवर आवश्यकताएँ】 लौटाते हैं; मॉडल के लिए हम जो तय ढाँचा जोड़ते हैं वह किसी फ़ील्ड में नहीं आता (इतिहास डेटा भी इसी तरह साफ़ किया गया है);
न सहेजे पैरामीटर का अंदाज़ा न लगाएँ: extended में न हो तो तब दर्ज नहीं हुआ — कारण retention से समझाएँ।

पैरामीटर संरक्षण नोट

parameter_retention "साफ़ तौर पर खाली मान भेजा गया" और "यह फ़ील्ड ऐतिहासिक रूप से कभी सहेजा नहीं गया" को अलग करता है:

core_parameters_available: मुख्य गाना कार्य रिकॉर्ड मौजूद है या नहीं; सही विवरण में आम तौर पर true;
extended_parameters_available: जुड़ा विस्तारित संगीत कार्य रिकॉर्ड मिला या नहीं;
sources: यह प्रतिक्रिया किन डेटा तालिकाओं से आई;
unavailable_fields: वे फ़ील्ड जो इतिहास से भरोसेमंद ढंग से नहीं निकाले जा सकते; parameters में इनका मान null होता है।

सामान्य इतिहास गानों में आम तौर पर प्रॉम्प्ट, स्टाइल, मौजूदा शीर्षक, मॉडल, जनरेशन प्रकार और स्रोत गाना सहेजा गया, पर सभी उन्नत पैरामीटर अलग से नहीं। प्लेटफ़ॉर्म generation_type से गायब मान का अंदाज़ा कभी नहीं लगाता।

कुछ विस्तारित संगीत कार्यों ने मूल प्रॉम्प्ट, स्टाइल, शीर्षक, मॉडल और साथ में custom_mode, negative_tags, vocal_gender, style_weight और weirdness_constraint भी सहेजा। विस्तारित रिकॉर्ड होने पर भी instrumental, lyrics_mode और wait_audio न मिल सकें।

शीर्षक बाद में उपयोगकर्ता बदल सकता है। जब सामान्य इतिहास कार्य ने मूल शीर्षक अलग नहीं सहेजा, तो parameters.title मौजूदा शीर्षक हो सकता है; विस्तारित कार्य रिकॉर्ड होने पर उसमें सहेजा मूल जनरेशन शीर्षक प्राथमिकता पाता है।

नहीं मिला या अनुमति नहीं

व्यावसायिक त्रुटियाँ एक समान प्रतिक्रिया लिफ़ाफ़े का उपयोग करती हैं। जब गाना मौजूद न हो या मौजूदा खाते का न हो:

{
  "success": false,
  "message": "song not found"
}

यह व्यावसायिक त्रुटि अभी HTTP 200 के साथ लौटती है, इसलिए नतीजा success फ़ील्ड से तय करें। API कुंजी न हो, अमान्य हो, समाप्त हो या बंद हो तो HTTP 401 मिलता है।

सुरक्षा नोट

इतिहास और विवरण एंडपॉइंट कभी नहीं लौटाते:

API कुंजी या Token ID;
कोटा, बिलिंग या धनवापसी फ़ील्ड;
खाता जानकारी या कच्ची प्रतिक्रिया;
ऑब्जेक्ट स्टोरेज की आंतरिक कुंजियाँ;
एडमिन त्रुटियाँ और आंतरिक संसाधन त्रुटियाँ।

अगलाटाइमस्टैम्प वाला गीत API

API कुंजी प्राप्त करें

रजिस्टर करने के बाद कंसोल में API कुंजी बनाएँ। प्रत्येक जनरेशन का खर्च 0.6 युआन है और 2 ट्रैक मिलते हैं, डाउनलोड असीमित हैं और फ़ोन नंबर की ज़रूरत नहीं है।

API कुंजी लें अवलोकन पर लौटें

गाना क्वेरी और इतिहास API

प्रमाणीकरण और डेटा दायरा

1. जनरेशन स्थिति पूछना

Headers

Body पैरामीटर

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

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

संगतता नोट

2. खाते का गाना इतिहास पूछना

Query पैरामीटर

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

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

प्रतिक्रिया फ़ील्ड

3. जनरेशन पैरामीटर पूछना

पाथ पैरामीटर

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

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

parameters फ़ील्ड

prompt_view फ़ील्ड (प्रॉम्प्ट देखें, 2026-09-28 को जोड़ा गया)

पैरामीटर संरक्षण नोट

नहीं मिला या अनुमति नहीं

सुरक्षा नोट

API कुंजी प्राप्त करें

`parameters` फ़ील्ड

`prompt_view` फ़ील्ड (प्रॉम्प्ट देखें, 2026-09-28 को जोड़ा गया)