واجهة الحصول على ملفات MIDI

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

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

تُحوّل واجهة MIDI المسارات التي تم فصلها إلى stems إلى ملف MIDI قياسي، للاستخدام في التوزيع أو العمل الإبداعي اللاحق أو الاستيراد في DAW.

لا يوفّر Suno عنوان تنزيل لملفات MIDI، بل يوفّر فقط بيانات النوتات لكل مسار (درجة الصوت، وقت البداية والنهاية، شدة العزف). وهذه الواجهة تحوّل بيانات النوتات إلى ملف MIDI قياسي (SMF format 1) وتعيده مباشرةً، لذا ما تحصل عليه دائماً ملف .mid حقيقي يمكن لـ DAW فتحه.

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

هذه الصفحة مثال مخصّص لملفات MIDI. والوصف الكامل لعائلة التنزيل (عناوين الوسائط، ملف واحد، التجميع، الاستماع أثناء التوليد) موجود في واجهة تنزيل وسَماع وسائط الأغاني.

الفوترة: مجاني. تقرأ هذه الواجهة بيانات نوتات الـ stems الموجودة ولا تخصم من الرصيد.

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

Headers

معاملات الجسم

مثال الطلب

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",
    "kind": "midi"
  }' \
  --output track.mid

الاستجابة

جسم الاستجابة هو المحتوى الثنائي لملف MIDI، وليس JSON.

الحصول على عنوان التنزيل

إذا أردت العنوان أولاً ثم التنزيل (مثلاً لتجميع عدة ملفات)، فاستدعِ أولاً:

curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id":"stem_clip_id","kind":"midi"}'

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "stem_clip_id",
    "kind": "midi",
    "url": "https://www.suno-api.io/api/music/download?song_id=stem_clip_id&kind=midi"
  }
}

يحتاج هذا العنوان أيضاً إلى ترويسة Authorization؛ وبدون مفتاح API تُعاد الاستجابة 401.

حول ملف MIDI

ملاحظات

• صالحة فقط للمسارات التي تم فصلها إلى stems: يجب أن يكون song_id معرّف مسار تُعيده /api/music/separate، لا معرّف الأغنية الأصلية.
• عدم وجود نوتات في stem نتيجة طبيعية: بعض المسارات (مثل FX) لا تحتوي نوتات قابلة للتدوين؛ وفي هذه الحالة يُعاد ملف MIDI صالح بدون نوتات بدلاً من خطأ.
• MIDI يحتوي على معلومات النوتات فقط: مستوى الصوت والتوزيع والتأثيرات ليست ضمن MIDI، فعليك ضبط الآلة بنفسك في DAW.
• اطلب كل مسار على حدة: الطلب الواحد يُعيد ملف .mid لمسار واحد؛ ولعدة مسارات استدعِ كل مسار أو استخدم تنزيل الحزم في Create UI.