واجهة الرفع ثم الغلاف في خطوة واحدة

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

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

الرفع ثم الغلاف في خطوة واحدة يرسل ملف صوت أو رابط صوت ويولّد نسخة غلاف جديدة من ذلك الصوت المصدر.

نقطة النهاية: POST /api/music/upload-cover

الفوترة: مدفوع، وحالياً 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. راجع «أوقات الانتظار وإعدادات المهلة» في نظرة عامة على الواجهة الجديدة.

عندما يكون الصوت كبيراً، يُستحسن فصل «الرفع» و«الكوفر» إلى خطوتين (موصى به)

تتطلب هذه الواجهة وضع الصوت كاملاً في جسم الطلب: فكلما كبر الصوت كبر الجسم، وأي اضطراب في الشبكة أو انتهاء للمهلة يقطع النقل في منتصفه، فيعيد الخادم unexpected end of JSON input (رمز HTTP 400، دون خصم).

وعندما يتجاوز الصوت نحو 8 ميجابايت، أو تكون الشبكة غير مستقرة، أو ستُستخدم المادة المصدر نفسها أكثر من مرة، فانتقل إلى الصيغة ذات الخطوتين:

1. POST /api/music/upload-source يرفع الصوت المصدر أولاً — مجاناً وقابل لإعادة المحاولة في أي وقت — ويعيد clip_id؛
2. POST /api/music/generate-from-source يبدأ الكوفر بذلك clip_id — جسم الطلب في الخطوة المدفوعة لا يتجاوز نحو 250 بايت.

راجع واجهة رفع الصوت المصدر، وواجهة الكوفر من مقطع مصدر، وقسم «الملفات الكبيرة والطلبات المقتطعة» في نهاية هذه الصفحة.

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

Headers

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

وحدة cover_start_s وcover_end_s هي الثانية، ويمكن استخدام الكسور العشرية؛ ويجب أن يكون وقت البداية أصغر من وقت النهاية وألا يتجاوز مدة الصوت المصدر. وعند حذف الحقلين معاً يُستخدم الصوت كاملاً. وتُربط audio_weight بحقل metadata.control_sliders.audio_weight في Suno وتتحكم في مقدار اعتماد النتيجة على الصوت المرجعي؛ وتأخذ 0.0-1.0، ولا يجوز إرسالها إلا إذا كان الطلب يحمل صوتاً مرجعياً صالحاً في file_url أو file_base64. والقيمة 0 صالحة، وحذف الحقل يعني «غير محدد» ويحتفظ بسلوك Suno الافتراضي. ويجب أن تكون instrumental وwaitAudio قيمتين منطقيتين بصيغة JSON لا نصوصاً.

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

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "كلمات جديدة أو اتجاه التعديل",
    "style": "Mandopop, acoustic guitar",
    "title": "نسخة الكوفر",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

الاستجابة

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "نسخة الكوفر",
        "status": "pending"
      }
    ]
  }
}

الملفات الكبيرة والطلبات المقتطعة

الموصى به: فصل الرفع والكوفر إلى خطوتين

الواجهة ذات الخطوة الواحدة (هذه) تدمج الرفع والتوليد في خطوة واحدة: الجسم الكبير يقع في تلك الخطوة الوحيدة، ولذلك عند انقطاعها لا تعرف هل جرى توليد شيء ولا هل خُصم مبلغ.

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

ما معنى 400 unexpected end of JSON input

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

1. اقتطاع جسم كبير أثناء النقل: تسجّل طبقة الدخول كلاً من «عدد البايتات التي أعلن العميل أنه سيرسلها» و«عدد البايتات التي وصلت فعلاً». وفي حالة مقيسة: أعلن العميل 14.17 ميجابايت ولم يصل سوى 11.8–12.4 ميجابايت، وتوقفت الطلبات الثلاثة كلها عند نحو 1.6–1.7 ثانية؛ وكان عدد البايتات الناقصة مختلفاً في كل مرة، ما يشير إلى انقطاع في النقل لا إلى حدّ ثابت (فالخادم لا يحدّ حجم جسم الطلب).
2. عدم تطابق Content-Length مع البايتات المُرسلة فعلاً: ففي Node.js، استخدام .length للنص (وهو عدد محارف UTF-16) كطول يُنتج حساباً خاطئاً بمجرد أن يحتوي المحتوى على اللغة الصينية أو نص متعدد البايتات.
3. كتابة الجسم كنص بدل Buffer، فيختلف عدد البايتات المكتوبة عن المُعلن.

وتحدث الحالات الثلاث قبل الخصم، فلا يترتب عليها أي تكلفة.

قائمة تحقق ذاتي على جانب العميل

• يُستخرج Content-Length من Buffer.byteLength(json, 'utf8') (أو Buffer.from(json).length) — ولا يُستخدم json.length أبداً؛
• يُكتب جسم الطلب كـ Buffer لا كنص؛
• مهلة المقبس / الطلب ≥ 300 ثانية؛
• عندما يتجاوز الصوت نحو 8 ميجابايت: استخدم file_url (فالجسم بضع مئات من البايتات)، أو رفع multipart من upload-source، أو انتقل مباشرةً إلى الصيغة ذات الخطوتين؛
• في طلبات multipart لا تضبط Content-Type يدوياً (اترك للعميل إضافة boundary)؛
• اطبع «عدد البايتات المُرسلة فعلاً» وقارنه بـ Content-Length؛
• في الصيغة ذات الخطوتين، تأكد من أن الخطوة 1 أعادت clip_id مع status في حالة الاكتمال قبل إرسال الخطوة 2.

أخطاء شائعة

واجهات ذات صلة: واجهة رفع الصوت المصدر (الخطوة 1)، وواجهة الكوفر من مقطع مصدر (الخطوة 2).