واجهة الكلمات ذات الطوابع الزمنية

آخر تحديث 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)» في واجهة تنزيل وسَماع وسائط الأغاني.

وفيما يلي نسخة كاملة مع ترشيح علامات الآلات/البنية (مقطع واحد لكل سطر، وهي مناسبة للتحقق من شكل البيانات أولاً):

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: [...] }. أما الوثائق الحالية فتعتمد مصفوفة الخط الزمني المُعادة مباشرةً.