واجهة Replace Section (استبدال مقطع)

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

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

تُعيد Replace Section توليد نطاق زمني واحد من أغنية موجودة في مكانه. وهي مناسبة لتصحيح سطر من الكلمات أو استبدال مقطع.

نقطة النهاية: POST /api/music/replace-section

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

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

Headers

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

startSeconds و endSeconds بالثواني ويقبلان الأعداد العشرية؛ ويجب أن يكون startSeconds أصغر من endSeconds وأن يقع النطاق داخل مدة الأغنية الأصلية. أما requestedAt فيُستخدم فقط عند الحاجة إلى تمرير وقت الطلب، كطابع زمني Unix بالثواني (لا بالملي ثانية)، ويمكن عادةً إغفاله.

الاستبدال مهمة غير متزامنة أيضاً. وقد يبدأ الـ clip المُعاد بحالة pending، وكون عنوان الصوت فارغاً عند ذلك أمر طبيعي؛ استخدم song_id الحقيقي المُعاد لاستعلام النتيجة النهائية.

طول المقطع: 2 ثانية على الأقل (مهم)

النطاق المطلوب استبداله لا يمكن أن يقل عن ثانيتين. وبالقياس: نطاقات 1.0 / 1.2 / 1.5 ثانية فشلت كلها، أما 2.0 ثانية وأكثر فنجحت.

وعندما يكون النطاق قصيراً جداً لا تُعيد المنصة «خطأ في المعاملات»، بل رسالة يسهل فهمها خطأً:

{"error":{"message":"You don't have access to this model. Upgrade your plan to use it.",
          "type":"bad_response_status_code","code":"bad_response_status_code"}}

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

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/replace-section \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "audioId": "clip_id",
    "startSeconds": 30,
    "endSeconds": 45,
    "contextLyrics": "كلمات السياق الكاملة",
    "contextWindowLyrics": "كلمات سياق النافذة",
    "infillLyrics": "الكلمات بعد الاستبدال",
    "style": "Mandopop, acoustic",
    "title": "النسخة المستبدلة",
    "negativeTags": "noise"
  }'

الاستجابة

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "replace_clip_id",
        "song_title": "النسخة المستبدلة",
        "status": "pending"
      }
    ],
    "replaceTask": "infill",
    "clipId": "clip_id",
    "source_update": {}
  }
}

الحقول المتوافقة

• audioId / audio_id / clipId / clip_id
• startSeconds / start_seconds / infillStartS / infill_start_s
• endSeconds / end_seconds / infillEndS / infill_end_s
• infillLyrics / infill_lyrics / replacementLyrics / replacement_lyrics
• style / tags
• negativeTags / negative_tags