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 کیلوبایت بود).

ساخت فایل .lrc

این نقطه پایانی فقط دادهٔ تایم‌لاین را برمی‌گرداند و فایل را مستقیم بازنمی‌گرداند. اگر .lrc لازم دارید، خطوط را از start_s برگشتی در قالب [mm:ss.cc] بسازید (فیلد word خودش خط جدید دارد، پس بر پایهٔ خط تقسیم کنید و خطوط خالی را رد کنید). برای نمونه به بخش «چگونه متن ترانه با مهر زمانی (.lrc) را بگیریم» در API دانلود و پیش‌نمایش رسانه آهنگ نگاه کنید.

در زیر نسخهٔ کامل با فیلتر نشانه‌های سازی/ساختاری آمده است (هر قطعه یک خط، مناسب برای بررسی نخستین شکل داده):

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: [...] } استفاده شده بود. مستندات کنونی، آرایه تایم‌لاینی را که مستقیماً برگردانده می‌شود معتبر می‌داند.