واجهة إضافة الموسيقى التصويرية

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

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

إضافة الموسيقى التصويرية تُعيد توزيع أغنية موجودة، أو تضيف إليها آلات، أو تنشئ بنية مصاحبة جديدة.

نقطة النهاية: POST /api/music/add-instrumental

الفوترة: مدفوع، وتُحاسَب حسب النموذج المطلوب؛ والمبلغ المخصوم فعلاً يتبع إعداد الأسعار في لوحة الإدارة.

Max Mode / Variety: تدعم نقطة النهاية هذه المعاملين الاختياريين max_mode و variety (0-4). عند تشغيل max_mode تُحاسَب هذه المرة بسعر مضاعف؛ وvariety لا يضيف أي تكلفة. معنى كل منهما وطريقة إرساله في قسم «المعاملات المتقدمة» من نظرة عامة على الواجهة الجديدة.

النموذج الموصى به: suno-v6. ويتوفر suno-v6 و suno-v6-wild و suno-v6-mini.

أوقات الانتظار والمهلات (مهم): هذه نقطة نهاية متزامنة — لا يُقبل الطلب ويُسلَّم إلى التوليد إلا عند وصول الاستجابة. ووفق القياس، تعود معظم الطلبات في 1-3 ثوانٍ، ونحو 10% تتجاوز 30 ثانية، وأطولها نحو 230 ثانية. اضبط مهلة العميل على 300 ثانية أو أكثر؛ وعدم وصول استجابة لا يعني عدم التوليد، ولا تُعد المحاولة فوراً بعد انتهاء المهلة (فذلك يكرر الطلب ويخصم مرة أخرى). وإن انقطع الاتصال فتحقق لاحقاً عبر GET /api/music/songs. راجع «أوقات الانتظار وإعدادات المهلة» في نظرة عامة على الواجهة الجديدة.

المصادقة

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

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/add-instrumental \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "source_clip_id": "source_song_id",
    "lyrics": "",
    "style_tags": "cinematic, strings, acoustic guitar",
    "song_title": "نسخة معزَّزة بالموسيقى",
    "audio_weight": 1,
    "wait_completion": false
  }'

الاستجابة

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "result_song_id",
        "song_title": "نسخة معزَّزة بالموسيقى",
        "status": "pending"
      },
      {
        "song_id": "result_song_id_2",
        "song_title": "نسخة معزَّزة بالموسيقى",
        "status": "pending"
      }
    ]
  }
}

يعيد الطلب الواحد نتيجتين (تُحاسَب كأغنيتين)؛ والمثال يعرض نتيجتين. فاعتمد على طول مصفوفة clips ولا تكتب حلقة بعدد ثابت. احفظ clips[].song_id ثم استعلم عبر واجهة استعلام الأغاني والسجل دورياً حتى تصل إلى completed. بعد ذلك يمكنك التشغيل أو التنزيل عبر audio_url؛ راجع واجهة إنشاء وجلب ملف WAV وبقية واجهات التنزيل.

ملاحظات

• يجب أن يكون source_clip_id معرّف أغنية حقيقياً مكتملاً ومتاحاً لمفتاح API الحالي؛ ولا يمكن استخدام معرّف بديل مثل pending:.
• إضافة الموسيقى التصويرية ليست كوفر؛ وإذا أردت كوفر فاستخدم واجهة الكوفر من مقطع مصدر.
• إذا أردت إضافة آلة أو مسار معيّن إلى أغنية موجودة فاستخدم واجهة إضافة مسار.