واجهة الفصل (الغناء والموسيقى المصاحبة)

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

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

يُستخدم الفصل لتقسيم أغنية موجودة إلى غناء أو موسيقى مصاحبة أو نتائج متعددة المسارات. التسلسل الموصى به للربط:

1. إذا لم يكن الصوت المصدر أغنية مولّدة على هذه المنصة، فاستدعِ أولاً واجهة رفع الصوت المصدر.
2. استدعِ POST /api/music/separate لإرسال مهمة الفصل.
3. استعلم عن النتيجة عبر واجهة استعلام الأغاني والسجل.
4. استخدم واجهات التنزيل لتنزيل ملف صوت كل نتيجة فصل.

نقطة النهاية: POST /api/music/separate

الفوترة: مدفوع. stem_mode=two حالياً 0.6 يوان افتراضياً لكل طلب؛ أما stem_mode=twelve فهو فصل متعدد المسارات وحالياً 3.0 يوان افتراضياً لكل طلب. والمبلغ المخصوم فعلاً يتبع إعداد الأسعار في لوحة الإدارة.

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

المصادقة

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

شرح stem_mode

شرح الفصل

الفصل قدرة ثابتة مستقلة، ولا يلزم إدخال أو اختيار نموذج لتوليد الأغاني. يرسل العميل الأغنية المصدر وstem_mode فقط؛ ويتولى الخادم المعالجة حسب الوضع.

من أين تأتي الأعداد: الطلب الواحد يُنتج نسختين (نتيجتان من المادة نفسها)، لذا العدد = 2 × عدد مسارات ذلك الوضع: 4 في two و24 في twelve. اعتمد دائماً على الطول الفعلي لمصفوفة clips في الاستجابة، ولا تكتب حلقة بعدد ثابت (فقد يفشل بعض المسارات وتُعاد المسارات الناجحة كالمعتاد).

ما المسارات التي يعيدها كل وضع

مسارات وضع twelve الاثنا عشر (الأسماء تمنحها المنصة بشكل ثابت، وقد يتغيّر الترتيب):

وضع two يعيد مسارين هما (Vocals) و(Instrumental)، لكل منهما نسختان. عناوين المسارات في two وtwelve هي أسماء ثابتة (لا تحمل اسم الأغنية المصدر)، فلا تتوقع أن تعرف من العنوان أي أغنية هي.

لا يمكن استخدام عناوين المسارات كمفتاح فريد. في النسختين تظهر مسارات بالاسم نفسه (مثل مسارَي (Vocals) ومسارَي (Strings))، كما أن عملية الفصل الواحدة تعيد مسارات كثيرة. استخدم دائماً song_id كمعرّف، وsong_title للعرض فقط؛ ولا تستخدم فهارس المصفوفة أيضاً (فالترتيب قد يتغيّر).

أمثلة الطلب

فصل الغناء / الموسيقى المصاحبة (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

الفصل متعدد المسارات (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

الاستجابة

عند النجاح تُعاد عادةً مصفوفة نتائج الفصل. وكل نتيجة مقطع أغنية مستقل، ويلزم الاستعلام عنها حتى تصبح status في حالة الاكتمال.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

ما سبق يعرض عنصرين فقط من 4 في وضع two؛ أما فعلياً فتُعاد 4 عناصر (نسختان × {(Vocals), (Instrumental)})؛ ويعيد وضع twelve أربعة وعشرين عنصراً. والعدد الحقيقي هو طول مصفوفة clips.

عادةً لا يحتاج العميل إلا إلى حفظ clips[].song_id؛ فالاستعلام والتنزيل لاحقاً يدوران حول هذه المعرّفات.

ملاحظات

• نتائج الفصل لا تظهر في سجل GET /api/music/songs (فذلك السجل يعيد الأغاني المولّدة العادية فقط). وبعد نجاح الطلب احفظ clips[].song_id فوراً، وإلا لن تجدها لاحقاً.
• كل مسار عمل مستقل: لكل مسار song_id خاص به، ويجب الاستعلام عنه حتى الاكتمال وتنزيله على حدة.
• الفوترة لا علاقة لها بعدد العناصر: تُحتسب لكل طلب (two 0.6 يوان لكل طلب، وtwelve 3.0 يوان لكل طلب)، وسواء أُعيد 4 عناصر أم 24 فالسعر نفسه.
• التنزيل: استخدم song_id لذلك المسار مع POST /api/music/download-url / download-file (مجاناً)، أو استخدم audio_url من نتيجة الاستعلام مباشرة؛ وللحصول على MIDI راجع واجهة الحصول على ملفات MIDI.
• لا تُعد الإرسال: الفصل نقطة نهاية متزامنة، لذا بعد انتهاء المهلة تحقق أولاً عبر استعلام الأغاني، ولا تُعد المحاولة مباشرة (فذلك يكرر الطلب ويخصم مرة أخرى).
• أخفِ المسارات التي لم تعد تحتاجها عبر واجهة حذف المسارات.

الاستعلام عن نتائج الفصل

بعد نجاح الطلب، استخدم clips[].song_id لاستدعاء POST /api/music/query للاستعلام عن النتيجة.

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

مثال استعلام مكتمل:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

تنزيل ملفات المسارات

بعد اكتمال نتيجة الفصل يمكنك تنزيل ملف مسار واحد عبر واجهة التنزيل.

نقطة النهاية: POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

قيم kind المدعومة:

ولتنزيل موارد نتيجة فصل واحدة في حزمة واحدة، استدعِ:

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

شرح الحالات

أخطاء شائعة

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

استخدمت الوثائق الأقدم أمثلة بكائن واحد مثل success/task_id/vocals_url/instrumental_url. أما الفصل الحالي فيعتمد على مصفوفة الأغاني clips[]: لكل نتيجة فصل song_id خاص بها، والاستعلام والتنزيل لاحقاً يدوران حول هذه المعرّفات.

واجهات ذات صلة

• إذا أردت فقط فصل الغناء عن الموسيقى المصاحبة دون اختيار وضع، فاستخدم واجهة إزالة الغناء، فهي الصيغة السريعة ذات المسارين لهذه الواجهة وهي مجانية حالياً.
• أخفِ مسارات الفصل التي لم تعد تحتاجها عبر واجهة حذف المسارات (حذف منطقي، دون خصم).
• للحصول على MIDI لأي مسار راجع واجهة الحصول على ملفات MIDI، وللحصول على الصوت والغلاف وغيرها من الوسائط راجع واجهة تنزيل ومعاينة وسائط الأغنية.