واجهة تنزيل Free2

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

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

Free2 قناة تنزيل مدفوعة منفصلة: تستخرج ملفات MP3/WAV/الكلمات/البيانات الوصفية من معرّف الأغنية (أو من رابط أغنية على suno.com) وتعيد عناوين تنزيل مُستضافة على المنصة. لا تقبل إلا مفتاح API، ولا تقبل جلسة تسجيل الدخول من المتصفح، ولا يتضمّن الرد مصدر التشغيل المشفّر من Suno.

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

الفوترة: تُحتسب حسب عدد الأغاني الناجحة، والافتراضي الحالي 0.2 يوان لكل أغنية. اختيار عدة أنواع ملفات في الطلب نفسه لا يضيف تكلفة، والأغاني التي تعذّر استخراجها لا تُحتسب. الحد الأقصى 10 أغانٍ في الطلب الواحد (بعد إزالة التكرار)، والمبلغ المخصوم فعلاً يتبع إعداد الأسعار في لوحة الإدارة.

النموذج الموصى به: suno-v6. تتوفر suno-v6 وsuno-v6-wild وsuno-v6-mini.

المصادقة

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

يجب تقديم song_id أو song_ids على الأقل، وقيمة واحدة على الأقل في files.

مثال الطلب

curl -X POST https://www.suno-api.io/api/music/free2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["song_id_1", "song_id_2"],
    "files": ["mp3", "wav", "lyrics"]
  }'

الاستجابة

{
  "code": 200,
  "message": "success",
  "data": {
    "songs": [
      {
        "song_id": "song_id_1",
        "files": [
          {"type": "mp3", "url": "https://media.suno-api.io/assets/song_id_1-free2-v1-mp3.mp3"}
        ]
      },
      {
        "song_id": "song_id_2",
        "files": [],
        "error": {"code": "song_not_found", "message": "song not found or not owned by the current user"}
      }
    ],
    "requested_songs": 2,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

عند طلب أغنية واحدة فقط، يعيد الرد أيضاً الحقلين العلويين song_id وfiles، توافقاً مع صيغة الأغنية الواحدة القديمة.

إعادة استخدام العناوين المخزّنة مؤقتاً (بدون رسوم)

في الأغاني التي نزّلتها من قبل، لا يحتاج التنزيل مرة أخرى إلى استخراج جديد ولا يُحتسب عليك مرة ثانية: استخدم POST /api/music/free2/cached لاسترجاع العناوين الحالية للملفات التي نزّلها هذا الحساب سابقاً.

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

الفوترة: مجاني. إنه تخزين مؤقت للقراءة فقط: لا استخراج ولا تحويل ولا خصم؛ يعيد فقط العناوين الجاهزة والتي لم تُستعَد بعد.

⚠️ صلاحية عنوان التنزيل: 7 أيام — احفظه في الوقت المناسب. تُوفَّر songs[].files[].url من تخزين الكائنات في المنصة وتنتهي افتراضياً بعد 7 أيام (تُستعاد الملفات ويعيد العنوان القديم الخطأ 404)؛ فاحفظها في مساحتك الخاصة خلال هذه الأيام السبعة. وبعد انتهاء الصلاحية، استدعِ POST /api/music/free2 من جديد لإعادة تحضير الملفات والحصول على عنوان صالح جديد (تُحتسب إعادة التحضير وفق قواعد الفوترة المعتادة؛ أما /api/music/free2/cached فلا يعيد إلا عناوين التخزين المؤقت الصالحة).

معاملات الطلب: مطابقة تماماً لـ POST /api/music/free2 (أحد الحقول song_id / song_ids / songs، وقيمة واحدة على الأقل في files).

curl -X POST https://www.suno-api.io/api/music/free2/cached \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "song_ids": ["98ca3f1d-…", "a185b3d9-…"], "files": ["mp3"] }'

{
  "success": true,
  "data": {
    "items": [
      { "song_id": "98ca3f1d-…", "type": "mp3", "url": "https://…/assets/98ca3f1d-…-free2-v1-mp3.mp3" }
    ],
    "songs": [
      { "song_id": "98ca3f1d-…", "files": [ { "type": "mp3", "url": "https://…" } ], "missing_files": [] },
      { "song_id": "a185b3d9-…", "files": [], "missing_files": ["mp3"] }
    ],
    "missing": ["a185b3d9-…"]
  }
}

لا تُعاد العناوين إلا للأغاني التي نزّلتها سابقاً؛ أما الأغاني التي لا سجل تنزيل لها أو التي استُعيدت أصولها فتظهر في missing فقط دون أي عنوان.

ملاحظات

• يستطيع POST /api/music/free2 استخراج أي أغنية عامة على Suno (بما في ذلك أغانٍ غير موجودة على منصتنا)؛ وعند تعذّر استخراج أغنية يُعاد error لتلك الأغنية وحدها، ولا تتأثر بقية الأغاني في الدفعة نفسها. أما POST /api/music/free2/cached فلا يعيد العناوين إلا للأغاني التي نزّلها هذا الحساب.
• أول استخراج لأغنية ينشئ الملفات المُستضافة، ثم يُعاد استخدامها بعد ذلك؛ لا تمرّر النوع نفسه مرتين في files، فالخادم يزيل التكرار تلقائياً.
• الفرق عن واجهة تنزيل ومعاينة وسائط الأغنية: Free2 مدفوعة، وتدعم تمرير روابط suno.com مباشرة، ولا توفّر أنواع الخط الزمني/MIDI إلى جانب الكلمات.