واجهة الكوفر من مقطع مصدر

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

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

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

نقطة النهاية: POST /api/music/generate-from-source

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

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

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

الاستخدام الموصى به: هذه هي الخطوة 2 من «الكوفر بخطوتين». في الخطوة 1 ارفع الملف عبر واجهة رفع الصوت المصدر (مجاناً) واحتفظ بقيمة clip_id؛ وفي الخطوة 2 استدعِ نقطة النهاية هذه لبدء الكوفر. بهذه الطريقة لا يظهر الصوت إلا في الخطوة المجانية: إن فشل الرفع فأعد المحاولة ببساطة دون أي خصم، بينما جسم الطلب في الخطوة المدفوعة لا يتجاوز بضع مئات من البايتات، لذا يكاد لا يفشل بسبب انقطاع النقل. أما واجهة الرفع ثم الغلاف في خطوة واحدة فتضع الصوت كاملاً في جسم الطلب، ولذلك بمجرد أن يتجاوز الصوت نحو 8 ميجابايت يُقتطع بسهولة أثناء النقل وتعيد unexpected end of JSON input (راجع «الملفات الكبيرة والطلبات المقتطعة» في تلك الصفحة).

كذلك يمكن إعادة استخدام المقطع clip_id نفسه مع Extend وReplace Section والفصل إلى مسارات وإجراءات لاحقة أخرى، دون إعادة رفع الصوت.

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

Headers

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

تأخذ weirdnessConstraint وstyleWeight وaudio_weight كسراً عشرياً بنسبة من 0.0 إلى 1.0، لا عدداً صحيحاً بالنسبة المئوية؛ فمثلاً 50% تُكتب 0.5. والقيمة 0 صالحة، ولا يعني «غير محدد» إلا حذف الحقل. وتُربط audio_weight بحقل metadata.control_sliders.audio_weight في Suno وتتحكم في مقدار اعتماد النتيجة على الصوت المرجعي؛ ولا يجوز إرسالها إلا إذا كان الطلب يحمل sourceClipId صالحاً أو صوتاً مرجعياً، فلا ترسلها في توليد نصي عادي. وعند customMode=true اكتب الكلمات الجديدة في prompt وقدّم style وtitle معاً؛ وعند customMode=false اكتب وصف الإبداع في prompt. ويجب أن تستخدم instrumental وwaitAudio قيمتي JSON المنطقيتين true/false.

تعيد نقطة النهاية هذه افتراضياً بشكل غير متزامن. وعندما تكون قيمة status المُعادة pending فإن خلو audio_url أمر طبيعي؛ فانتظر الاكتمال قبل استخدام عنوان الصوت. ويجب أن تكون sourceClipId معرّف أغنية/مقطع مصدر حقيقياً — لا تستخدم task_id أو client_request_id أو معرّفاً بديلاً مثل pending:.

ما نوع المعرّف sourceClipId

sourceClipId هو معرّف مقطع Suno الحقيقي المستخدم كمصدر لهذا الكوفر. وعادةً ما يُسمّى هذا المعرّف في كائن الأغنية الموجّه للعميل على المنصة song_id، بينما تحتفظ معاملات طلب الكوفر بالاسم sourceClipId؛ وهنا يعني الاثنان معرّف الأغنية الحقيقي نفسه.

وإذا كان المصدر رفعاً معزّزاً، فاستعلم أولاً عن مهمة الرفع المعزّز وانتظر حتى يصبح status هو completed، ثم ضع song_id الحقيقي المُعاد في sourceClipId. ويُستحسن أيضاً وضع audio_url وtitle من تلك النتيجة في sourceAudioUrl وsourceTitle.

لا تضع task_id أو client_request_id أو معرّف الرفع البديل pending:enhanced-upload:* في sourceClipId.

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/generate-from-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "sourceClipId": "uploaded_or_existing_clip_id",
    "sourceAudioUrl": "https://example.com/source.mp3",
    "sourceTitle": "عنوان الصوت الأصلي",
    "prompt": "كلمات جديدة أو اتجاه إبداعي",
    "customMode": true,
    "style": "Mandopop, warm vocal",
    "title": "عنوان الكوفر",
    "negativeTags": "noise",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false
  }'

الاستجابة

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "عنوان الكوفر",
        "status": "pending"
      }
    ],
    "source_update": {}
  }
}

ملاحظات

تحاول نقطة النهاية هذه معالجة مسألة الحساب الذي ينتمي إليه المقطع المصدر. وإذا تعذّر استخدام المقطع المصدر مباشرةً، فقد يعيد الخادم رفعه بناءً على معلومات الصوت المصدر ثم يولّد النتيجة.