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

آخر تحديث 2026-09-18 · فريق Suno-API

هذه ليست تعرّفاً صوتياً. النص يعتمد دائماً على كلماتك الأصلية كما أرسلتها؛ ونحن نضع كل حرف في اللحظة الصحيحة فقط — لذا لا تحدث أبداً حالة «أحرف سُمعت خطأً فانحرفت الكلمات».

وصف نقطة النهاية

تُحاذي الكلمات الموجودة مع الصوت وتعيد طوابع زمنية على مستوى السطر وعلى مستوى الحرف، لتسليط الضوء حرفاً بحرف بأسلوب الكاريوكي، والكلمات المتدحرجة، وتوليد الترجمات.

نقطة النهاية: POST /api/music/lyrics-align

المصادقة: راجع المصادقة؛ الترويسة هي Authorization: Bearer YOUR_API_KEY

الفوترة: لكل طلب (حالياً 0.1 يوان افتراضياً لكل طلب)؛ وإذا كانت أغنية من المنصة وقد حُدّد فصل الغناء، فتُحتسب مرة أخرى بسعر «فصل الغناء/الموسيقى المصاحبة» في المنصة. والمبلغ المخصوم فعلاً يتبع إعداد الأسعار في لوحة الإدارة.

الزمن المتوسط: 5–15 ثانية (حسب طول الصوت وما إذا كان فصل الغناء سيتم في اللحظة)

لماذا نحتاج المعايرة: طوابع زمنية من جهة التوليد ليست دقيقة دائماً

تعيد واجهة الكلمات ذات الطوابع الزمنية الطوابع الزمنية كلمةً كلمة من جهة التوليد مباشرةً، وهي غير دقيقة:

• التكرارات والهارموني الكثيف والراب والنوتات الطويلة تنحرف غالباً ككتلة أو تُزيح أحرفاً مفردة؛
• بعض الأغاني ينقصها مقطع في البداية (مثل مقدمة موسيقية صافية، حيث يبدأ أول جزء بعد الثانية عشرة)؛
• بعض الأسطر يصعب ربطها بمرتكز زمني واضح.

تعيد المعايرة بناء محاذاة الوقت على أساس الكلمات التي تقدّمها أنت: يُصحَّح الوقت فقط، ولا يُغيَّر النص أبداً — وهو مناسب للحالات التي يُهم فيها «هل ينطبق تماماً» (تسليط الضوء حرفاً بحرف كما في KTV، وترجمات لكل حرف، وتقييم الغناء معاً).

الطريقة الموصى بها (ثلاث خطوات، أفضل نتيجة)

1. استخرج الغناء الصافي أولاً (فصل الغناء/الموسيقى المصاحبة) وحاذِ فقط مسار الغناء — فلا تزعجك الموسيقى ولا الهارموني. الأساس القياسي: في مقارنة سطراً بسطر بين «المزيج الكامل ومسار الغناء» للأغنية نفسها، اختلف 5 من 28 سطراً بأكثر من 0.25 ثانية (الأكبر 2.64 ثانية)؛ واختلف محرّكان مستقلان بمتوسط 0.239 ثانية على مسار الغناء و0.508 ثانية على المزيج الكامل — أي تناسق يقلّ للنصف تقريباً. لذا يُنصح بتشغيله لتسليط الضوء حرفاً بحرف (KTV/الترجمات). (وجاري إعادة قياس مقدار التحسّن بالمحرّك الجديد.)
2. قدّم الكلمات كاملة: الأغنية كلها، سطراً سطراً، بمقابلة واحد لواحد مع الصوت. أي جملة أو مقطع ناقص يُزيح كل الأسطر التالية؛ ولا تُدرج في الكلمات طوابع مثل [00:23.82] (فتُتجاهل تلقائياً).
3. في أغاني المنصة يكفي تحديد vocal_separate: true لننجز «الفصل + المحاذاة» في خطوة واحدة.

ثلاث طرق للاستخدام

علاقة المعاملات (أكثر موضع يخطئ فيه الناس — اقرأه بعناية)

• إرسال song_id → مسار أغنية المنصة: لا ترسل معه lyrics أو audio_url أو audio_object_key؛
• إرسال audio_url أو audio_object_key → مسار الأغنية الخارجية: واحد فقط من الاثنين، ولا ترسل song_id؛
• vocal_separate يعمل فقط مع أغاني المنصة، وإرساله مع أغنية خارجية يُرفض (الصوت ليس عندنا فلا يمكن فصله).

جديد: رفع ملف محلي مباشرةً (الصوت لا يمرّ عبر خوادمنا)

استخدمه عندما يكون الصوت على جهازك ولا تريد رفعه أولاً إلى مساحتك العامة. خطوتان:

1. POST /api/music/lyrics-align/upload-ticket مع file_name / file_size / content_type فتحصل على put_url (رابط موقّع لا يحتوي بيانات اعتماد طويلة الأجل) وobject_key؛
2. أرسل الملف بـ PUT إلى put_url، مع إرفاق content_type الوارد في الاستجابة كما هو (فهو داخل التوقيع؛ تغيير حرف واحد يعني 403)؛
3. عند إرسال طلب المحاذاة، أرسل audio_object_key بدلاً من audio_url.

الاعتماد للاستخدام مرة واحدة: بعد انتهاء المحاذاة (نجاحاً أو فشلاً) يحذف الخادم هذا الكائن، وإعادة استخدام المفتاح نفسه تُرجع خطأ.

جديد: لم تعد الكلمات إلزامية

سابقاً كانت الأغنية الخارجية تتطلب كلمات. الآن يمكن عدم إرسالها: يجري الخادم تعرّفاً واحداً ويستخدم النص المتعرَّف عليه ككلمات.

ويجب قول الثمن بوضوح: يصبح النص تابعاً لنتيجة التعرّف، وقد تكون بعض الأحرف غير دقيقة. وتُوسم هذه الاستجابات بـ lyrics_source: "asr" وconfidence: "low"، وفي warnings[] يظهر {"code":"no_reference_lyrics"}.

لإنشاء تسليط الضوء حرفاً بحرف / KTV، احرص دائماً على تقديم الكلمات الأصلية.

معاملات الطلب

Headers

معاملات جسم الطلب

القيود

أمثلة الطلب

أغنية خارجية (كلمات + عنوان الصوت)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lyrics": "أسير في شوارع باردة\nنسيم الليل يلامس عينيّ\nالزمن يمضي كالماء",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

أغنية من المنصة (دون فصل)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2"}'

أغنية من المنصة + فصل الغناء (موصى به للكاريوكي)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2", "vocal_separate": true}'

الاستجابة

استجابة ناجحة

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "أسير في شوارع باردة",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "أ", "start": 21.66, "end": 21.74, "word": true},
        {"char": "س", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

شرح الحقول

كيف تستخدم coverage (ثلاث درجات)

الحالة والأوقات

حد التنفيذ الواحد على الخادم 8 دقائق؛ اضبط مهلة العميل على 120 ثانية أو أكثر.

استجابات الخطأ

{
  "success": false,
  "message": "音频超过 6 分钟上限（实际 7.2 分钟）"
}

المبدأ: لا نتيجة نهائية يعني استرداداً كاملاً. لا يُخصم إلا عند إعادة الطوابع الزمنية لكل حرف فعلاً، والاسترداد تلقائي دون طلب.

الفوترة

التركيب:

المستحق = السعر الأساسي + (لا كلمات ? رسم النسخ : 0) + (فصل محدَّد ? سعر الفصل : 0)

رسم فصل الغناء يُحتسب مرة واحدة: إن كنت قد فصلت الأغنية ومسار الغناء متاح مباشرةً تحتسبه هذه الواجهة؛ وإن لزم الفصل في اللحظة تحتسبه خطوة الفصل.

مثال كامل (Python)

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://www.suno-api.io"

def align_lyrics(song_id=None, lyrics=None, audio_url=None, vocal_separate=False):
    payload = {}
    if song_id:
        payload["song_id"] = song_id
        payload["vocal_separate"] = vocal_separate
    else:
        payload["lyrics"] = lyrics
        payload["audio_url"] = audio_url

    r = requests.post(
        f"{BASE}/api/music/lyrics-align",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=600,
    )
    data = r.json()
    if not data.get("success"):
        raise RuntimeError(data.get("message"))
    return data


res = align_lyrics(song_id="17e52af7-b5df-4877-a98a-dce94e0e6aa2", vocal_separate=True)
print("جودة المحاذاة coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # كاريوكي لكل حرف: كل حرف في line["chars"] له start / end خاص به

أسئلة شائعة

س: هل النتيجة لكل حرف أم لكل سطر؟ ج: كلاهما. lines[].start لكل سطر، وlines[].chars[].start / end لكل حرف؛ والمشغّل يأخذ ما يحتاجه.

س: لماذا النص المُعاد مطابق لما أرسلته؟ ج: هذا هو التصميم. لا نتعرّف ثم نعيد الكتابة، بل نحاذي الوقت فقط، فلا يمكن أن «تُصحَّح الكلمات إلى خطأ إملائي».

س: coverage مرتفع لكن ما زال يبدو منزاحاً قليلاً. ج: خطأ المحاذاة لكل حرف عادة في حدود عشرات المللي ثانية؛ وإذا كان الانزياح ثابتاً في الأغنية كلها فالسبب الأرجح صمت في بداية الصوت — اقتطعه ثم أعد المحاولة.

س: لماذا كان فصل الغناء يعمل قبل قليل ثم صار يقول «مسار الغناء غير متاح»؟ ج: نتائج الفصل هي عناوين مؤقتة قصيرة الأجل (بالقياس: تنتهي بعد نحو نصف ساعة). وفي هذه الحالة تحاول الواجهة الفصل تلقائياً مرة أخرى؛ وإن فشلت يقع استرداد كامل. لذا فإن «افصل الآن ثم عاير لاحقاً» غير موثوق — نفّذ الأمرين في التدفق نفسه.

س: هل يجب أن أفصل أغنية المنصة بنفسي؟ ج: لا. مع vocal_separate: true نتحقق هل للأغنية مسار غناء؛ وإن لم يوجد مسار صالح نُرجع خطأ ونسترد، ولا نمرّر المزيج الكامل.

س: هل يمكن بشكل دفعات؟ ج: أغنية واحدة لكل طلب. وللدفعات كرّر الاستدعاء؛ وكل استدعاء يُحتسب طبيعياً، لذا يُنصح بتخزين النتائج محلياً.

س: هل تُحفظ النتيجة؟ ج: هذه الواجهة لا تحفظ شيئاً؛ احفظ القيمة المُعادة بنفسك (طوابع السطر والحرف كلها في الاستجابة).