सरल मोड जनरेशन API

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

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

सरल मोड जनरेशन एक वाक्य के विवरण को पूरा गाना बना देती है। सेवा आपके विवरण से बोल, धुन, संगीत-संयोजन और गायन खुद लिखती है।

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

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

Max Mode / Variety: यह एंडपॉइंट वैकल्पिक पैरामीटर max_mode और variety (0-4) समर्थित करता है। max_mode चालू होने पर यह कॉल 2× दर पर बिल होती है (0.6 → 1.2 युआन प्रति कॉल); variety का कोई अतिरिक्त शुल्क नहीं है। दोनों का अर्थ और भेजने का तरीका नए API का अवलोकन के "उन्नत पैरामीटर" भाग में है।

सुझाया गया मॉडल: suno-v6

प्रतीक्षा समय और टाइमआउट (ज़रूरी): यह सिंक्रोनस एंडपॉइंट है — ऑर्डर तभी स्वीकार होता है और जनरेशन को सौंपा जाता है जब जवाब आ जाता है। मापन के अनुसार ज़्यादातर अनुरोध 1-3 सेकंड में जवाब देते हैं, लगभग 10% 30 सेकंड से ज़्यादा लेते हैं और सबसे लंबा लगभग 230 सेकंड का होता है। क्लाइंट टाइमआउट 300 सेकंड या ज़्यादा रखें; जवाब न आना इसका मतलब नहीं कि कुछ बना नहीं, और टाइमआउट के तुरंत बाद दोबारा कोशिश न करें (इससे ऑर्डर दोहरा होता है और दोबारा शुल्क लगता है)। अगर कनेक्शन टूट गया हो, तो बाद में GET /api/music/songs से जाँचें। नए API का अवलोकन में "प्रतीक्षा समय और टाइमआउट सेटिंग" देखें।

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

Headers

Body पैरामीटर

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

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "समुद्र किनारे की गर्मियों पर एक ज़िंदादिल मंदारिन पॉप गाना",
    "instrumental": false,
    "wait_completion": false
  }'

संदर्भ सामग्री references (वैकल्पिक)

references एक सरणी है जो इस जनरेशन से "संदर्भ सामग्री" जोड़ती है। यह पूरी तरह वैकल्पिक है (छोड़ने पर व्यवहार पहले जैसा ही रहता है), और आप एक ही तरह या कोई भी संयोजन जोड़ सकते हैं।

तत्व प्रकार

नियम

• संदर्भ गानों का क्रम ही उनका अर्थ-क्रम है: जिस क्रम में चाहें उसी में भेजें (जैसे "धुन पहले से, गायन दूसरे से")।
• style_prompt / lyrics / duration_s सभी छोड़े जा सकते हैं; प्लेटफ़ॉर्म उन्हें गाने की जानकारी से भर देता है, और आपका भेजा हुआ मान्य होता है।
• पूरी तरह वाद्य गानों में lyrics "" या "[Instrumental]" हो सकता है।
• संदर्भ चित्र jpeg / png / webp समर्थित करते हैं, हर एक 10MB तक, बॉडी के साथ base64 में भेजे जाते हैं।
• कई संदर्भ गाने जोड़ते समय accept_mode=async भी इस्तेमाल करें (ऊपर "रसीद-स्वीकृति मोड"): सेवा को पहले सामग्री तैयार करनी होती है, इसलिए सिंक्रोनस इंतज़ार लंबा हो सकता है।

उदाहरण: दो संदर्भ गाने

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "description": "इन विचारों को एक गाने में जोड़ें",
    "references": [
      { "type": "song", "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
      { "type": "song", "song_id": "a90438d2-35fc-4443-88f4-56531e6e5d24" }
    ]
  }'

उदाहरण: संदर्भ गाना + पुरानी आवाज़

{
  "model": "suno-v6",
  "description": "इन विचारों को इस आवाज़ में गाएँ",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "voice", "voice_id": "5813cbe1-36f1-414a-a9a8-4d399dfeb292" }
  ]
}

उदाहरण: संदर्भ गाना + संदर्भ चित्र

{
  "model": "suno-v6",
  "description": "इस चित्र का माहौल पकड़ें",
  "references": [
    { "type": "song",  "song_id": "43eb711d-81f8-4e72-a68e-b2498bac88f9" },
    { "type": "image", "base64": "data:image/jpeg;base64,/9j/4AAQ..." }
  ]
}

पैरामीटर त्रुटियाँ

ये मामले HTTP 400 लौटाते हैं, किसी भी शुल्क से पहले रोक दिए जाते हैं, इसलिए इनका कोई खर्च नहीं:

references[0] में दिया नंबर उस तत्व की सरणी में अनुक्रमणिका है, इसलिए गलत तत्व ढूँढना आसान है।

प्रतिक्रिया

गानों की सरणी, आम तौर पर 2 कार्य या गाने।

[
  {
    "song_id": "clip_id",
    "song_title": "गर्मियों की समुद्री हवा",
    "status": "pending",
    "description": "समुद्र किनारे की गर्मियों पर एक ज़िंदादिल मंदारिन पॉप गाना",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

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

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

• अनुरोध बॉडी में "accept_mode": "async" जोड़ें
• हेडर X-Accept-Mode: async जोड़ें

चालू होने पर एंडपॉइंट तुरंत HTTP 202 लौटाता है, जिसका अर्थ सिर्फ़ "स्वीकार हुआ और जनरेशन कतार में गया" है, जबकि जनरेशन पृष्ठभूमि में चलता रहता है:

{
  "success": true,
  "data": {
    "request_id": "ac_20260920092714315816800d76fv3nq",
    "status": "queued",
    "accepted_at": 1789896434,
    "pre_consumed_quota": 300000,
    "tasks": [
      { "index": 0, "status": "queued" },
      { "index": 1, "status": "queued" }
    ]
  }
}

स्वीकृति चरण में song_id नहीं लौटता। अभी कोई असली गाना ID नहीं है, और न request_id न tasks[].index गाना ID हैं — इन्हें song_id के रूप में न सहेजें। असली song_id नीचे प्रगति क्वेरी में दिखता है।

स्वीकृति प्रगति पूछना

एंडपॉइंट: GET /api/music/requests/{request_id} (मुफ़्त, उसी API कुंजी से प्रमाणित)

curl "https://www.suno-api.io/api/music/requests/ac_20260920092714315816800d76fv3nq" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "request_id": "ac_20260920092714315816800d76fv3nq",
    "status": "processing",
    "tasks": [
      { "index": 0, "status": "processing", "song_id": "f3fa09f5-3d55-4953-826c-0d23f043ec57" },
      { "index": 1, "status": "processing", "song_id": "5fcafe3e-3fae-4d64-8f66-c01bc027b0c3" }
    ]
  }
}

हर status मान का अर्थ:

हर कार्य का अपना tasks[].status भी है, मान वही जो गाना क्वेरी API में हैं: pending (भेजा गया, बन रहा है), processing, completed, failed। कार्य आइटम में title, duration और पहले से दर्ज audio_url भी हो सकते हैं; जो नहीं है वह अभी बना नहीं है।

असली song_id मिलने के बाद गाना क्वेरी API या डाउनलोड एंडपॉइंट से आगे बढ़ें।

Python उदाहरण

import time
import requests

BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

accepted = requests.post(
    f"{BASE}/api/music/create",
    headers={**HEADERS, "Idempotency-Key": "your-own-unique-key"},
    json={"description": "एक ज़िंदादिल पॉप गाना", "model": "suno-v6", "accept_mode": "async"},
    timeout=300,
).json()["data"]

request_id = accepted["request_id"]
while True:
    time.sleep(5)
    progress = requests.get(
        f"{BASE}/api/music/requests/{request_id}", headers=HEADERS, timeout=60
    ).json()["data"]
    if progress["status"] in ("completed", "failed"):
        print(progress)
        break

संगतता और नोट

• accept_mode के बिना व्यवहार पहले जैसा ही है: सिंक्रोनस इंतज़ार, 200 और गानों की सरणी। मौजूदा इंटीग्रेशन को कुछ बदलने की ज़रूरत नहीं।
• यह स्विच अभी केवल POST /api/music/create और POST /api/music/create/custom पर काम करता है; बाकी जनरेशन एंडपॉइंट इसे अभी समर्थित नहीं करते।
• साथ में Idempotency-Key भी भेजें (आपकी अपनी अनूठी स्ट्रिंग, ≤128 अक्षर): वही कुंजी दोबारा भेजने पर केवल एक बार स्वीकार होती है, दोबारा भेजने पर वही रसीद मिलती है और दोहरा शुल्क नहीं लगता। असिंक्रोनस मोड में यह और भी ज़रूरी है।
• accept_mode=async के साथ wait_completion अनदेखा हो जाता है (रसीद तुरंत लौटती है, गानों का इंतज़ार नहीं करती)।
• शुल्क फिर भी ऑर्डर स्वीकार होते समय पहले काटा जाता है; विफल जनरेशन स्वतः पूरा वापस हो जाता है।
• टेक्स्ट फ़ील्ड की सीमा: description में अधिकतम 3000 अक्षर आते हैं (Unicode अक्षरों में गिनती, एक हान अक्षर 1 गिना जाता है)। इससे लंबा टेक्स्ट सीधे HTTP 400 लौटाता है, जनरेशन में नहीं जाता और शुल्क नहीं लगता, और त्रुटि संदेश में मापी गई लंबाई आती है, जैसे description must not exceed 3000 characters; received 4120। इस एंडपॉइंट में बोल/स्टाइल फ़ील्ड नहीं हैं; उनके लिए कस्टम मोड जनरेशन API में "टेक्स्ट फ़ील्ड की सीमा" देखें। सामान्य नियम नए API का अवलोकन के "टेक्स्ट फ़ील्ड की सीमाएँ" में हैं।
• references के बिना व्यवहार, कीमत और प्रतिक्रिया पहले जैसी ही हैं: मौजूदा इंटीग्रेशन को कुछ बदलने की ज़रूरत नहीं।
• संदर्भ सामग्री जोड़ी गई हो (ख़ासकर कई गाने) तो लंबे सिंक्रोनस इंतज़ार के बजाय accept_mode=async रसीद मोड चुनें; सामग्री तैयार होने का समय उसकी मात्रा और स्रोत पर निर्भर है।

आगे के चरण

अगर जवाब आते समय गाने पूरे नहीं हुए हैं, तो अंतिम परिणाम के लिए गाना क्वेरी API इस्तेमाल करें।

Node/Electron इंटीग्रेशन उदाहरण

अगर आप Electron के मुख्य प्रोसेस, Node.js सर्वर या डेस्कटॉप क्लाइंट में सामान्य जनरेशन जोड़ रहे हैं, तो सुझाया गया प्रवाह यह है:

1. जनरेशन कार्य बनाने के लिए POST /api/music/create कॉल करें।
2. जवाब से song_id या id पढ़ें।
3. स्थिति देखने के लिए हर 2 सेकंड में POST /api/music/query कॉल करें।
4. नतीजे में audio_url दिखते ही जनरेशन पूरा मानें।

पुराने रास्ते POST /api/generate या GET /api/clip?id=... इस्तेमाल करना बंद कर दें; ये मौजूदा सुझाए गए सार्वजनिक इंटीग्रेशन की सतह का हिस्सा नहीं हैं।

const http = require('http');
const https = require('https');

const BASE_URL = 'https://www.suno-api.io';
const MODEL = 'suno-v6';
const POLL_INTERVAL_MS = 2000;
const MAX_POLL_ATTEMPTS = 60;

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function requestJson(urlString, apiKey, body) {
  const url = new URL(urlString);
  const transport = url.protocol === 'https:' ? https : http;
  const payload = JSON.stringify(body);

  return new Promise((resolve, reject) => {
    const req = transport.request(
      {
        method: 'POST',
        hostname: url.hostname,
        port: url.port || undefined,
        path: `${url.pathname}${url.search}`,
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
          'Content-Length': Buffer.byteLength(payload),
        },
      },
      (res) => {
        let raw = '';

        res.setEncoding('utf8');
        res.on('data', (chunk) => {
          raw += chunk;
        });
        res.on('end', () => {
          const data = raw ? JSON.parse(raw) : {};

          if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
            reject(new Error(`Suno API request failed: HTTP ${res.statusCode} ${raw}`));
            return;
          }

          resolve(data);
        });
      }
    );

    req.on('error', reject);
    req.write(payload);
    req.end();
  });
}

function getPayload(response) {
  return response && response.data !== undefined ? response.data : response;
}

function toSongList(payload) {
  if (Array.isArray(payload)) return payload;
  if (Array.isArray(payload?.songs)) return payload.songs;
  if (Array.isArray(payload?.clips)) return payload.clips;
  return payload ? [payload] : [];
}

function collectSongIds(createResponse) {
  return toSongList(getPayload(createResponse))
    .map((song) => song.song_id || song.id)
    .filter(Boolean);
}

async function generateSunoSong({ apiKey, description, instrumental = false }) {
  const createResponse = await requestJson(`${BASE_URL}/api/music/create`, apiKey, {
    description,
    model: MODEL,
    instrumental,
    wait_completion: false,
  });

  const songIds = collectSongIds(createResponse);
  if (songIds.length === 0) {
    throw new Error(`Suno API did not return song ids: ${JSON.stringify(createResponse)}`);
  }

  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
    await sleep(POLL_INTERVAL_MS);

    const queryResponse = await requestJson(`${BASE_URL}/api/music/query`, apiKey, {
      song_ids: songIds,
      model: MODEL,
    });

    const songs = toSongList(getPayload(queryResponse));
    const completed = songs.find((song) => song.audio_url);

    if (completed) {
      return {
        audioUrl: completed.audio_url,
        title: completed.song_title || completed.title || 'Suno Song',
        duration: completed.duration,
      };
    }

    const allFailed = songs.length > 0 && songs.every((song) =>
      ['failed', 'error', 'rejected'].includes(String(song.status || '').toLowerCase())
    );

    if (allFailed) {
      throw new Error(`Suno generation failed: ${JSON.stringify(songs)}`);
    }
  }

  throw new Error('Suno generation timed out after 120 seconds. Please query again later.');
}

// Usage:
// generateSunoSong({
//   apiKey: process.env.SUNO_API_KEY,
//   description: 'A bright pop song about the ocean in summer',
// }).then(console.log).catch(console.error);

असली प्रोजेक्ट में API कुंजी सर्वर पर्यावरण चर, डेस्कटॉप क्लाइंट सेटिंग या सुरक्षित भंडार में रखें — कभी फ़्रंट-एंड कोड में नहीं और कभी रिपॉज़िटरी में कमिट न करें।