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

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

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

टाइमस्टैम्प वाला गीत किसी गाने के शब्द-स्तरीय टाइमस्टैम्प लाता है, जिससे गीत को सिंक में दिखाया जा सके।

एंडपॉइंट: POST /api/lyrics/timeline

बिलिंग: निःशुल्क (केवल-पढ़ने की क्वेरी; कोई शुल्क नहीं लगता और कोई जनरेशन कार्य नहीं बनता)।

रिटर्न प्रारूप: टाइमलाइन सरणी सीधे लौटाई जाती है — data / success का कोई बाहरी आवरण नहीं है; पार्स करने पर यह सिर्फ़ एक सरणी है।

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

Headers

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

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

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_id": "clip_id"
  }'

प्रतिक्रिया

नीचे प्रोडक्शन से 189.6 सेकंड के suno-v6 गाने की असली प्रतिक्रिया है (उस कॉल में कुल 69 खंड थे; यहाँ सिर्फ़ पहले और आख़िरी कुछ खंड रखे गए हैं):

[
  {
    "word": "[Intro]\n\n\n[",
    "start_s": 15,
    "end_s": 15.04277,
    "success": true,
    "p_align": 0.99
  },
  {
    "word": "Instrumental: ",
    "start_s": 15.04704,
    "end_s": 15.10264,
    "success": true,
    "p_align": 0.99
  },
  {
    "word": "End]\n\n\n",
    "start_s": 189.16974,
    "end_s": 189.654,
    "success": true,
    "p_align": 0.99
  }
]

फ़ील्ड संदर्भ

ध्यान देने योग्य बातें

1. बाहरी आवरण न खोजें। जवाब खुद सरणी है, {"data": ...} नहीं, और उसमें success फ़ील्ड भी नहीं है।
2. शुरुआत में कोई खंड न हो सकता है। सिर्फ़ प्रस्तावना वाले गानों में मापन से पहला खंड 15वें सेकंड पर ही दिखा, और start_s का 0 से शुरू होना तय नहीं है; काराओके के लिए शुरुआती खाली हिस्सा खुद संभालें।
3. वाद्य और संरचना चिह्न भी लौटाए जाते हैं, [Intro], [Verse 1], Instrumental: soft arpeggiating piano, …, [End] जैसे रूपों में, और उनके भी शब्द-दर-शब्द समय आते हैं। गीत के सबटाइटल बनाने से पहले इन खंडों को शुरुआती [ या Instrumental के आधार पर छाँट लें; वरना अरेंजमेंट के विवरण गीत की तरह दिखेंगे।
4. यह शब्द-आधारित है, पंक्ति-आधारित नहीं। एक ही गीत-पंक्ति अक्सर कई खंडों में बँटती है और उन्हें \n से पंक्तियों में जोड़ना पड़ता है; एक पंक्ति का समय उसके पहले खंड का start_s है।
5. खंडों की संख्या गाने पर निर्भर है; निश्चित संख्या मान न लें (मापन: 189.6 सेकंड के गाने में 69 खंड और लगभग 6.5 KB का जवाब)।

.lrc फ़ाइल बनाना

यह एंडपॉइंट सिर्फ़ टाइमलाइन डेटा लौटाता है; फ़ाइल सीधे नहीं लौटाता। .lrc चाहिए तो लौटाए गए start_s से [mm:ss.cc] प्रारूप में पंक्तियाँ बनाएँ (word फ़ील्ड में नई पंक्तियाँ हैं — पंक्ति के अनुसार तोड़ें और खाली पंक्तियाँ छोड़ें)। उदाहरण के लिए गाना मीडिया डाउनलोड और प्रीव्यू API में "टाइमस्टैम्प वाले गीत (.lrc) कैसे लें" देखें।

नीचे वाद्य/संरचना चिह्न छानने वाला पूरा रूप है (एक खंड एक पंक्ति, पहले डेटा का आकार जाँचने के लिए उपयुक्त):

import re

SKIP = re.compile(r"^\[.*\]$|^Instrumental:")

def to_lrc(segments):
    lines = []
    for seg in segments:
        if not seg.get("success", True):
            continue
        text = (seg.get("word") or "").strip()
        if not text or SKIP.match(text):
            continue
        cs = int(max(0.0, float(seg["start_s"])) * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

संगतता नोट

पुराने दस्तावेज़ों में { success, song_id, lyrics: [...] } आवरण ऑब्जेक्ट का उदाहरण था। मौजूदा नए दस्तावेज़ सीधे लौटाई गई टाइमलाइन सरणी को मान्य मानते हैं।