واجهة تنزيل ومعاينة وسائط الأغنية

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

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

تفصل هذه المجموعة من الواجهات بين «الحصول على عنوان الوسائط» و«تنزيل الملف فعلاً»:

• للحصول على عنوان يمكن تشغيله أو تنزيله مباشرةً (مثلاً لوضعه في مشغّلك أو نسخه إلى تخزين الكائنات): استخدم POST /api/music/download-url أو GET /api/music/download الموجود أصلاً في الاستجابة.
• لجعل المتصفح يحفظ الملف على القرص مباشرةً: استخدم POST /api/music/download-file (ملف واحد) أو POST /api/music/download-all (حزمة).
• إذا كانت الأغنية لا تزال قيد التوليد وتريد الاستماع أولاً: استخدم POST /api/music/generation-stream-url.

الفوترة: كلها مجانية. التنزيل والمعاينة يقرآن فقط وسائط تستضيفها المنصة بالفعل؛ ولا يستدعيان Suno ولا يُخصم مقابلها.

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

المصادقة

أنواع الوسائط المدعومة (kind)

1) الحصول على عنوان الوسائط

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": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

يُستخدم url للتشغيل أو للنسخ بنفسك؛ أما nav_url فيحمل Content-Disposition: attachment ويناسب لصقه مباشرةً في شريط عنوان المتصفح للتنزيل (يُستخدم عندما لا تدعم بعض متصفحات الجوال التنزيل عبر blob).

⚠️ صلاحية العنوان: 7 أيام — انقل الملف في الوقت المناسب

يشير url / nav_url إلى تخزين الكائنات في المنصة وينتهي افتراضياً بعد 7 أيام (تُستعاد الملفات ويعيد العنوان القديم الخطأ 404). انسخها إلى مساحتك الخاصة خلال هذه الأيام السبعة.

وبعد الانتهاء لا حاجة لإعادة توليد الأغنية: استدعِ POST /api/music/download-url مرة أخرى (أو مرّر refresh: true) للحصول على عناوين جديدة صالحة لتلك الأغنية. وهذه المجموعة من الواجهات مجانية ولا تضيف أي رسوم.

2) تنزيل ملف واحد مباشرةً

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": "song_id", "kind": "song"}' \
  -o song.mp3

جسم الاستجابة هو تدفق ملف (وليس JSON)، ويحمل Content-Disposition اسم الملف جاهزاً. ولا يمكن الحصول على الكلمات والكلمات ذات الطوابع الزمنية إلا عبر هذه الواجهة (download-url يعيد عناوين الوسائط فقط ولا يعيد الكلمات). وملف .lrc مدعوم حالياً لبعض الأغاني فقط؛ فإذا أعاد success:false فأنشئ .lrc بنفسك عبر واجهة الكلمات ذات الطوابع الزمنية كما في القسم التالي، دون إعادة المحاولة.

كيف تحصل على الكلمات ذات الطوابع الزمنية (.lrc)

يُنصح بخطوتين تصلحان لأي أغنية:

الخطوة 1: الحصول على الخط الزمني كلمةً كلمة (مجاناً)

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

النتيجة مصفوفة مباشرة (بلا غلاف data)؛ وكل عنصر بهذا الشكل: {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. ويحتوي word على أسطر جديدة بالفعل، لذا يمكن تقسيمه سطراً سطراً؛ ولمعاني الحقول وتصفية المقاطع الموسيقية وغيرها من التنبيهات راجع «الحقول» و«ملاحظات الاستخدام» في واجهة الكلمات ذات الطوابع الزمنية.

الخطوة 2: ركّب ملف .lrc بنفسك من start_s (صيغة الوقت [mm:ss.cc])

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

تستطيع GET /api/music/download?song_id=<id>&kind=lrc أيضاً تنزيل ملف .lrc الذي ينتجه الخادم مباشرةً، لكن حالياً تُدعم بعض الأغاني فقط: وإذا أعادت success:false فأنشئه بنفسك بالطريقة أعلاه — دون حاجة إلى إعادة المحاولة، ودون تأثير على الفوترة.

3) التنزيل كحزمة

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_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

استخدم song_id (أغنية واحدة) أو song_ids (دفعة، بحد أقصى 50 عنصراً). وجسم الاستجابة تدفق ZIP.

4) عنوان تنزيل ثابت

GET /api/music/download?song_id=<id>&kind=<kind> هو مدخل التنزيل المعطى مباشرةً في استجابات الأغنية. ويقبل مفتاح API وجلسة تسجيل الدخول معاً، ويعمل مثل download-file، ويناسب تثبيته في عميل أو مشغّل من طرف ثالث.

5) الاستماع أثناء التوليد

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

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

كون playable_until_completed يساوي true يعني أن هذا عنوان استماع مؤقت لأغنية قيد التوليد؛ فانتقل إلى العنوان الدائم بعد اكتمال الأغنية. وإذا فشلت أغنية واحدة فسيحمل ذلك العنصر حقل error، وتُعاد بقية الأغاني كالمعتاد.

ملاحظات

• كل الواجهات تعيد عناوين وسائط مستضافة على المنصة فقط؛ ولا تعيد أبداً مصدر Suno المشفّر ولا عنواناً موقّعاً مؤقتاً.
• العناوين ليست دائمة — انسخ الملفات بنفسك إن أردت حفظها طويلاً؛ واستخدم download-file عندما تحتاج الملف الأصلي على القرص.
• يتطلب ملف MIDI لأي مسار أن يكون فصل ذلك المسار قد اكتمل، وإلا يُعاد خطأ.